Copyright 1988 by Bdale Garbee, Phil Karn and Brian Lloyd.
All Rights Reserved.
This Document may be reproduced in whole
or in part for any non-commercial purpose,
as long as credit is given the authors.
1. Background and Overview
1.1. What's TCP/IP All About?
Charles Hedrick of RUTGERS, the State University of New Jersey, has written a very important document... a description of the "world of TCP/IP" that manages to be both a reasonable introduction for the non-technical or mildly technical individual, and an excellent starting point for anyone interested in learning more about the family of networking protocols commonly referred to as "TCP/IP".
The only difficulty with this document for those who are trying to learn more about TCP/IP in the Amateur Radio "Packet" environment, is that the experience Mr. Hedrick works from is almost entirely with the wired networks common in universities and businesses, where various computer systems are networked together using some form of wire (usually coaxial cable as in Ethernet, or fiber optic cabling as in Pronet).
The individual who is familiar with radio transmission will easily recognize differences between the wired environment and the on-air environment. This does not mean that the protocols are unfit for use on the air, it simply means that we need to be careful when *implementing* the protocols in software for use on the radio that we don't make assumptions that aren't valid on the air! In particular, wired networks allow the assumption that every host can hear every other host on the wire... quite unlike the situation in radio, where one-way propagation paths are often the norm.
Mr. Hedrick mentions several protocols that can "ride on top of" IP, such as Sun's Network File System, NFS. Some of the applications that he talks about, including NFS, while wonderful on wired networks, are somewhat unreasonable for packet radio until or unless we have *much* higher speed modems. Wired networks can easily run at 10 million bits per second, while packet ranges from 300 bits per second on HF, to perhaps 56 thousand bits per second with the WA4DSY modems on UHF. Therefore, some of the protocols such as NFS that like to eat lots of network bandwith won't be as neat on current packet radio as they are on current wired networks, but they certainly provides a dramatic improvement in potential services for the "next generation" of packet radio.
The KA9Q Internet Package is currently the most common TCP/IP implementation (if not the only one!) in use on Amateur Packet Radio. The software supports the IBM PC and clones, the Apple Macintosh, the Commodore Amiga, and both BSD and System 5 Unix variants. The package provides IP, ICMP, TCP, UDP, and ARP as basic services, and implements the FTP, Telnet, and SMTP protocols as applications. The package also includes a separate mail user interface program by N3EUA called BM, and software from WA3PXX for forwarding PBBS mail over TCP. An associated set of software packages provide replacement ROM firmware for several TNC's, allowing them to be used with the KA9Q TCP/IP Package. At least two commercial manufacturers, AEA and Kantronics, now support the KISS protocol in their TNC's, making them usable with TCP/IP.
Charles Hedrick's excellent introduction to TCP/IP can be found in the same place you found this document, named TUTORIAL.DOC. If you're new to all this, go find and read that before you get too wound up in the bits...
1.2. What's in the KA9Q Package
This is an overview of the various modules making up the KA9Q Amateur Radio Internet Protocol package. Each section first describes the protocol that is supported, followed by a description of the implementation.
1.2.1 Subnet Layer
1.2.1.1. Standard 10 megabit Ethernet
The driver provided is for the 3-Com 3C500 (IE) controller for the PC. Tight assembler loops are used instead of DMA for copying data in and out of the controller's buffer; this seems fast enough. Only the receiver is interrupt driven; incoming packets are placed on a queue which is then emptied at a more leisurely pace by the main loop code. Since Ethernet is so fast, the transmitter routine busy-waits for completion. The IE controller has only a single buffer which is shared between receive and transmit. Packets occasionally get lost under heavy load, especially when several TCP connections are active at once and/or the TCP receive window sizes are larger than the MSS values. This is very hard to fix without going to a newer, more reasonably designed controller.
1.2.1.2. Serial Line IP (SLIP)
SLIP is a very simple technique for sending Internet Datagrams across ordinary asynchronous lines (e.g., modems). Its only function is to delimit datagrams with framing characters, which are "byte stuffed" for transparency. No error checking is provided; the checksums that are part of IP, TCP and UDP are relied on for this. SLIP is popular on UNIX systems that support TCP/IP, so this represented the easiest way to get my package up and talking with other Internet sites. It also allows the use of existing AX.25 TNCs without modifying the latter, although this is should only be done as a stopgap measure until an HDLC link level driver can be integrated directly into the package.
1.2.1.3. AX.25/KISS TNC
Sends and receives IP and ARP datagrams encapsulated in AX.25 Unnumbered Information (UI) frames. This allows an unlimited number of simultaneous users on the local radio channel, since there are no connections at link level. The special AX.25 Level 3 Protocol ID values of hex CC (IP) and CD (ARP) are used.
With the 871225.0 release, support has also been added for encapsulating IP datagrams in "normal" AX.25 connected-mode packets. This was a natural by-product of adding full AX.25 level 2 session support to the package.
This mode of operation requires that the TNC run special "KISS TNC" code. Versions for the TNC-2, TNC-1, and VADCG/ASHBY boards are included in this distribution. Some manufacturers, including AEA and Kantronics, are adding support for KISS into their commercial TNC products. Note that this style of operation is NOT compatible with a "stock" TNC carrying SLIP format datagrams in connected mode.
The PC-100 is an I/O adapter card for the PC containing a Zilog 8530 Serial Communications Controller and two AMD 7910 World Chip modems. The encapsulation method is identical to (and compatible with) the AX.25/KISS TNC interface driver.
1.2.1.5. AX.25/Eagle Interface
There is a card available at some swapfests made by Eagle Computer Company that implements two ports using the Zilog 8530. External modems are required. This driver is very similar to (and may eventually be merged with) the PC-100 driver.
1.2.1.6. Address Resolution Protocol (ARP)
ARP is used for the automatic mapping of IP addresses to link or subnet addresses. While originally designed for the specific task of mapping IP to Ethernet addresses, the protocol is general enough to be used on any link or subnet that supports a broadcast facility. ARP is described in ARPA RFC-826.
Both Ethernet and AX.25 format addresses are currently supported. Instead of discarding a packet when an ARP request is sent, this implementation holds it on a queue for a limited time, pending a response to the request.
1.2.2. Internet Layer
1.2.2.1. Internet Protocol (IP)
IP is the universal network-level datagram protocol of the ARPA Internet. It corresponds roughly to level 3 of the ISO Reference Model (ISORM). (Actually, IP belongs to the 3B internetwork sublayer if you follow the amoeboid proliferation of ISO sublayers). Routines are provided to generate, receive and route (i.e., packet switch) IP datagrams. IP is specified in ARPA RFC-791 and MIL-STD-1777.
IP datagram fragmentation and reassembly is fully implemented. The IP options Loose Source Routing, Strict Source Routing and Record Route are supported; Stream ID, Security and Timestamp are ignored. (Few, if any, IP options are used extensively in the ARPA Internet). The IP module includes a routing (packet switching) facility; currently this consists of a table containing a list of host-specific destinations along with a "default" entry that may be used when the desired destination is not found in the table. No protocol is yet provided to actually manage the table; currently it must be done manually, either locally or remotely. NB! "Networks" (in the ARPA Class-A/B/C sense) are not yet understood, in that all entries in the routing table (except for the default entry) must be host-specific. This will be fixed in the future with a "generalized subnetting" scheme that will allow each entry in the table to have an arbitrary, variable length "subnet mask."
1.2.2.2. Internet Control Message Protocol (ICMP)
ICMP is the error reporting adjunct to IP. It appears as a pseudo-protocol on top of IP, but is actually considered to be part of IP. The IP routines automatically generate ICMP messages whenever an error occurs in the processing of IP datagrams; incoming ICMP messages are passed up to the originating end-to-end protocol for appropriate action. ICMP is specified in ARPA RFC-792.
This ICMP supports all options except ICMP Timestamps.
1.2.3. Host-Host Layer
1.2.3.1. Transmission Control Protocol (TCP)
TCP provides a reliable, sequenced "virtual circuit" or "connection-oriented" service atop IP on an end-to-end basis. It corresponds to the Transport layer (level 4) of the OSI model. Since a single TCP module supports multiple connections through the use of port numbers, it also provides Session (level 5) functionality without the need for a distinct layer. (Or it makes the session layer unnecessary, depending on your point of view). TCP is specified in ARPA RFC-793 and MIL-STD-1778.
The implementation supports an arbitrary number of simultaneous connections, limited only by memory space for control blocks. An "upcall" mechanism is available to notify the user of three events: connection state change, receive data available and transmit buffer space available. The Maximum Segment Size option is understood and used when it is received, and a global variable is used for generating MSS in outgoing segments. There is currently no provision for sending URGent data. The latest recommendations on "tinygram" avoidance (Nagle, ARPA RFC-896) are implemented and work quite well.
1.2.3.2. User Datagram Protocol (UDP)
UDP provides only a simple, unguaranteed "datagram" or "connectionless" service, adding only checksums and port multiplexing to the raw service provided by IP. As an alternative to TCP, UDP also sits at level 4 (and 5) of the ISORM. UDP is specified in ARPA RFC-768.
The implementation supports the creation of queues on local sockets. An upcall mechanism similar to that used in TCP notifies the user when datagrams have arrived.
1.2.4. Application Layer
1.2.4.1. File Transfer Procotol (FTP)
FTP is for transfer of binary or text files between hosts. FTP uses two TCP connections one for exchanging commands and responses in the form of ASCII strings, and the other for the actual data transfers. FTP is defined in ARPA RFC-959.
FTP is implemented in two parts, a server half and a client half. The server half supports multiple simultaneous remote users, although at the moment there is no access control; anyone may access, delete or overwrite any file on the machine. The client half is invoked by the "ftp" command.
1.2.4.2. Remote login protocol (Telnet)
Telnet is for logging into remote systems and negotiating various options, such as remote vs local echoing. Telnet itself is documented in ARPA RFC-854, with the many options defined in other RFCs.
The client half supports the ECHO and TRANSMIT-BINARY options; it is invoked by the "telnet" command. A telnet "server" has been written, but since MS-DOS isn't a timesharing system it is used for keyboard-to-keyboard conversations instead. An incoming connect request to the local Telnet port creates a local Telnet session and notifies the local user. He may then select the new session and carry out a conversation with the remote initiator.
1.2.4.3. Simple Mail Transfer Protocol (SMTP)
As the name implies, is used for the transfer of electronic mail between hosts. SMTP commands and responses are strings of ASCII characters resembling those used by FTP. SMTP uses a single TCP connection for both control and the actual mail messages. SMTP is described in ARPA RFC-821; headers in mail messages are described in RFC-822.
A simple version server (receiver) is implemented; it accepts mail from a remote sender and appends it to a mailbox. Mail forwarding, which accounts for much of the complexity in other mail servers, is not implemented. A mail client ("user agent") for composing and sending messages developed by Bdale Garbee, N3EUA, and others is included. It is called 'BM', and is documented elsewhere.
1.2.5. Session control
The user may manage several simultaneous Telnet and FTP client invocations. Only one client session is "active" at any one time, but the user may quickly switch between them. Terminal output arriving for an inactive session is held until that session is again made active. (Note that this is in addition to the multiple server sessions which go on automatically "in the background", i.e., without operator intervention).
The Internet package has been tested with and works under DoubleDos 4.0 by SoftLogic Solutions, allowing the system to be simultaneously "on the net" while executing conventional MS-DOS commands. The net program uses the special DoubleDos function call 0EEH to relinquish the processor when it isn't needed; this speeds up the task running in the other partition. This function is a "no-op" when DoubleDos isn't active.
2. Administrivia
2.1. What an "IP Address" is and How to Get One
IP Addresses are 32 bit numbers that uniquely identify a given machine (or "host") running the TCP/IP protocol suite. All of the possible 32 bit numbers are coordinated by an entity known as the Network Information Center, or NIC. Amateur Radio operators are fortunate in that a "Class A Subnet" consisting of 24 bits of address, in the range 44.X.X.X, has been reserved for our use. Brian Kantor, WB6CYT of San Diego, CA, now serves as the top level administrator of the 44.X.X.X address space, and assigns blocks of addresses to regional coordinators from around the world.
You need to have a unique address before you can link in with the rest of the networked world.
<insert info on how to get address>
2.2. Obtaining Software Updates
The KA9Q Internet software package is still evolving and growing. As a result, we occasionally issue updates to the software that fix bugs and/or update functionality. Announcements are always made to the USENET news group rec.ham-radio.packet, and in the bulletins on N3EUA's telephone BBS system. They usually also show up on Compuserve within a day or two. There is never any charge for the software. A small charge may exist for copying floppies if you want the bits on disk, and of course you'll have to pay the long distance if you grab the bits over the phone!
If several people are running the software in your area, get together and decide on one person to get the new bits, then copy it around. We won't mind.
2.2.1. From N3EUA's Phone BBS
The HIP Shack phone BBS, running Opus software, is reachable as Fidonet node 128/19, 303/495-2061. The BBS supports 300, 1200 and 2400 baud, is up 24hrs/day, and is configured to allow first-time users more than sufficient time to download the entire package in one phone call at 1200 baud.
The BBS is always the first place that the software is available. Beta-release executables for the PC can also occasionally be found here. You download and use these at your own risk! (Known as the "you get what you pay for" principle).
2.2.2. From N3EUA's Unix Machine
For those running Unix machines with UUCP capability, there is an anonymous UUCP login on winfree, N3EUA's BSD Unix machine, that can be used to download the software. This machine is up 24hrs/day, but only has one modem, and the modem stays fairly busy. A typical L.sys entry might be:
winfree Any ACU 2400 1-303-495-0492 ogin: Uanon word: notFTP
Start by transferring the file /usr/spool/uucppublic/pub/README for a list of the files available, and current release notes.
2.2.3. Via FTP on the Internet
The current revision of the software is available on SIMTEL20.ARPA within a few days of each release. The files usually reside in the directory PD1:<MISC.KA9Q-TCPIP>. Questions on the files on Simtel20 can be directed to W8SDZ@SIMTEL20.ARPA. Anonymous FTP's are allowed.
Beta-releases are often available on the machine LOUIE.UDEL.EDU, in the directory tree rooted at pub/ka9q. Anonymous FTP's are allowed, but unless you're working on the software, the bits on louie can be "dangerous", as they often include incompletely implemented features, and can have serious bugs. Caveat Emptor.
2.2.4. On PC Floppies
The Tucson Amateur Packet Radio association (TAPR) now provides floppy copies of the software on 360k PC floppies, and can provide KISS ROMs for various TNC's, at a nominal charge for duplication and shipping. Contact TAPR for more information.
2.2.5. On Native Media for Other Machines
Copies of the software for the Macintosh and Amiga are best obtained by downloading from an on-line source, or by copying a friend's disk. If all else fails, Mikel Matthews (the author of the Mac/Amiga port) is willing to make a small number of copies on native media for the Mac and/or Amiga. Mikel can be reached via UUCP mail at ...uiucdcs!addamax!mikel.
3. Installation of the Software
Installing the KA9Q Internet Package on your computer is not very hard, but if you haven't tried to do it before, it can be a bit confusing. The greatest efforts made so far towards making the process simple and understandable have been made by Brian Lloyd, WB6RQN. Much of this installation section is a direct copy of portions of his HOWTO.DOC document. Information about installation on machines other than the IBM clone family has come from various sources.
3.1. Configuring Your TNC for Network Operation
If you are using this software in a University or other wired-network environment, you may want to skip past the TNC installation section. All Hams should keep reading!
There are now several choices for TNCs to be used with the TCP/IP network code. Versions of the Keep It Simple Stupid TNC interface software (KISS) are available for the TNC-1, the TNC-2, the VADCG board and clones (Ashby), the Kantronics family of TNCs, and the AEA TNCs. Following are the different setup/configuration modes for the different TNCs.
3.1.1. TNC-1 or Heath HD-4040
The firmware for the TNC-1 is available in either a downloadable version or a stand alone version. I will describe only the stand alone version here. Locate the ROM labeled E000 and remove it. Insert the KISS PROM in its place making sure that you orient the prom in the same direction (failure to do so will result in smoked PROM). Connect your TNC-1 to your computer using an RS-232 cable. A cable that passes the signals from pins 2, 3, and 7 is sufficient
Since the TNC-1 has no switches for setting the baud rate to the computer the firmware has been "hard wired" to 4800 baud. See the documentation that comes with the TNC-1 version of KISS for instructions on how to patch the .HEX file for other baud rates.
3.1.2. TNC-2 and Clones
First step is to prepare your TNC-2 for use with TCP/IP. The standard firmware for the TNC-2 is not very computer friendly and, as such, is not very useful when it comes time to make your computer speak with other computers. To that end Mike Chepponis, K3MC, wrote the KISS (Keep It Simple Stupid) TNC code. There are two ROM versions for the TNC-2. The first is contained in a type 2764 or 27C64 EPROM. This version contains the KISS code in it. The second version is contained in a type 27256 or 27C256 EPROM and contains both the standard TAPR 1.1.3 TNC code and a loader that will permit you to download the KISS code into the TNC. Check the EPROM you have received and determine which type you have. If you are burning your own EPROMs you probably do not need these instructions.
Open up your TNC and locate the ROM. It is in the socket labeled "U23." Using a small nail file or screwdriver gently pry up the existing EPROM. Carefully press the new EPROM into place being sure that the orientation is the same. If you are installing the 2764 type of EPROM you will need to make a small modification to the TNC. There is a location on the board just above the first RAM socket labeled JMP-6. Turn the board over and cut the trace joining the two pads. Solder a two-pin jumper header in place. When using a type 2764 the jumper at JMP-6 should be removed and installed when a type 27256 EPROM is being used. That should complete the hardware part of the installation. As an alternative you may choose to burn the KISS code into a 27256 and not bother with jumpers.
Attach your TNC to your PC using an RS-232C cable. You can use the same cable that you were using to connect your PC to your TNC. If you are doing this for the first time and are not sure about your cabling, a cable with just pins 2, 3, and 7 passed through is sufficient. Some PCs like to see the signals Clear To Send (CTS, pin 5), Data Set Ready (DSR, pin 6), and Data Carrier Detect (DCD, pin 8) asserted. You can set this up by jumpering pin 4 to 5, and pin 20 to pins 6 and 8 at the female DB-25 connector that goes to the PC.
Now to verify that the TNC still works. Apply power to the TNC and turn it on. The STA, CON, and PWR LEDs should come on and the STA and CON lights should go out again about 1 second later. If you have the type 2764 EPROM with the KISS code in it one or both of the STA and CON LEDs will begin to flash. If the CON LED flashes you have 8Kb of RAM in the TNC. If the STA LED flashes you have 16Kb of RAM. If both LEDs flash you have 32 Kb of RAM. The flashing of the LEDs verifies the proper operation of the TNC.
If you got the combined loader and TAPR version EPROM, checkout is a slightly different process. You can test your TNC-2 using two methods. The first method is to connect your TNC to a terminal program and send the character 'h' or 'H' to the TNC. The result should be the standard TNC startup message. Exit from the 1.1.3 mode of operation by issuing the reset command to the TNC. The second method involves downloading the KISS code to the TNC. Use the mode command to set the baud rate of the comm port to the proper value, e.g. it matches the DIP switch setting on the back of the TNC, and copy the file tnc2kiss.hex to the appropriate comm port. The following command sequence will serve to download the KISS code to the TNC:
mode com1:4800
copy tnc2kiss.hex com1:
If the download was successful (it takes about one minute) the STA and/or CON LEDs will begin flashing as described in the previous paragraph. If the download is not successful check the cable from computer to TNC, check the baud rate on the TNC, and check to ensure that the computer is indeed sending data to the TNC. Once this is done the TNC is ready to use with the NET program.
NOTE: Running KISS causes the stored parameters in the TNC, i.e. MYCALL, NEWMODE, TXDELAY, etc., to be destroyed. Every time you shift from KISS to TAPR modes you MUST reset the parameters.
3.1.3. AEA PK-232, PK-87, or new Heath TNC (PK-232 clone)
If you have one of these boxes, congratulations! You do not have to change PROMS! KISS is already installed as a standard feature if you have a recent release of the firmware, 4-MAR-87 or later for the PK-232, or 21-JAN-87 or later for the PK-87, you have KISS in your TNC already. To make it work first ensure that your computer can communicate with the TNC in standard packet mode. This will ensure that the computer, TNC, cabling, and radio are all operating properly.
[Please note that one of the commands ("PACKET") is not valid on the PK-87 and will only elicit a "Huh?" response. Please note that comments have been added to the commands. Do not type the information following the double dash or type the double dash itself.]
Here is the sequence of commands that will turn on the KISS mode for the AEA products:
AWLEN 8 -- ensure it can speak 8 bit data
PARITY 0 -- no parity
RESTART -- warm reset; make the previous commands take effect
RAWHDLC on -- turn off AX25L2 (the protocol is now handled by the PC)
PPERSIST on -- turn off DWAIT and enable p-persistence
HOST on -- start KISS running
The PK-87 or the PK-232 will remain in the KISS mode until you send a break (~200ms of spacing) or until you send the command character three times (^C ^C ^C) in quick succession. Beware! Some terminal emulators (like YAPP) will send a break signal when you exit from them. That will undo your work and cause all manner of confusion. The terminal program PROCOMM seems to work just fine. The TNC may also be switched back to ordinary AX.25 mode by issuing the following command from within NET.EXE:
param ax0 255
3.1.4. Kantronics
Kantronics has recently begun to offer KISS on their products. It is the simplest of the commercial implementations of KISS to configure and use.
First setup and operate your KAM, KPC-II, or KPC-4 for standard packet operation. This will ensure that the computer, TNC, cabling, and radio are operating properly. Use your terminal program to send the following commands:
ABAUD 4800 -- set the baud rate to whatever you will be using when net is running (set by the attach command)
DWAIT 0 -- disable DWAIT
PERSIST 50 -- enable persistence and set it to about 20%
SLOTTIME 16 -- set the slot time to 160 ms
KISS ON -- Enable KISS mode at the next reset
PERM -- make the above command permanent so that KISS will be entered whenever the TNC is powered up
RESET -- start KISS
If you wish to have the the TNC revert back to ordinary AX.25 mode of operation you should omit the PERM command from the above sequence. That way the TNC will revert back to ordinary AX.25 mode when the power is removed and restored to the TNC. The TNC may be switched back to ordinary AX.25 mode by issuing the command:
param ax0 255
This command will work even if the PERM command has been used to make KISS the default mode of operation.
3.2. Installation of NET.EXE on an IBM PC or Clone
Create a directory called EXE and set that as the default directory. Use PKXARC to extract the files from EXE.ARC into the new directory. Should you not have PKXARC already, run the program PKX35A35.EXE provided with the distribution. This program will create the extraction utility and its documentation.
There are two programs that make up the network software: NET.EXE (the networking code) and BM.EXE (the mail program). Copy these programs from the EXE directory to the place on your hard disk where you keep command programs. If you are running on a floppy based system you should create a bootable floppy and copy these programs to the floppy.
Test to make sure that everything is there by executing the programs. Type the command "net" and, if the installation of the network code was successful, the message "KA9Q internet protocol package" and the prompt "net>" will appear on the screen. This means that the network code is running and awaiting commands.
Exit from the net code with the command "exit." Now run the command "bm." The screen should display the message "Bdale's Messy-DOS Mailer" and the prompt "Brian"> will appear (this prompt or something like it is a function of the content of the bm.rc configuration file). If all this has occurred, all is well so far. If you do not get this response from bm, do not be concerned. Try again after you have configured bm in the following steps.
3.2.1. Installing the Mail Directories used by BM
First step is to configure the mailer (BM). To make BM work properly you must create the following directories on your disk:
//spool
//spool//mail
//spool//mqueue
Copy the file SEQUENCE.SEQ to the /spool/mqueue directory. Copy the files HOSTS.NET and BM.RC to the root directory of the default drive used when net is running. If you are on a floppy based system you need to put BM.RC with NET.EXE, BM.EXE, AUTOEXEC.NET, HOSTS.NET, and AUTOEXEC.BAT in the root (/) directory (more on AUTOEXEC.NET later).
3.2.2. HOST.NET
You will need to edit the file HOSTS.NET to know about all the systems with which you will exchange mail. This is how net will translate the name into the IP address. Here is an example of some of the entries I have in my machine for other local TCP/IP stations:
44.96.0.2 wb2sef.ampr
44.96.0.16 n8fjb.ampr
44.96.0.17 ka3lyq.ampr Roel
All this does is translate the symbolic name to the IP address, e.g. WB2SEF gets translated to 44.96.0.2 so that IP can route it to the proper network node. This saves you from having to remember lots of numbers. You may note that the last entry has two aliases, either of which may be used to specify the IP address 44.96.0.17. There is essentially no limit to the number of aliases that may be listed for a single IP address. Just be sure that they are all on one line.
3.2.3. BM.RC
Next edit the file BM.RC. This file lets the mail system know about local host name, user name, and editor name. Here are some example entries:
host wb6rqn.ampr
user brian
edit emacs
The edit entry should contain the name of your favorite editor, such as edlin (edlin is not your favorite editor?). This editor will be used to construct a mail message when you invoke that function of bm. You may use any DOS compatible editor just so long as it has the capability to prepare ascii files (be careful if you specify a word processor -some word processors embed special characters in the file).
Later on you can read the documents BM.DOC and SMTP.DOC to get more information. You at least have enough info to get your mailer running now.
3.2.4. FTPUSERS
Now you need to possibly modify the /FTPUSERS file to permit users to send and receive files from your system. The FTPUSERS file contains the information about users in the following format:
user password /directory permission-code
The 'user' entry is the user's name, 'password' is the password for that user, '/directory' is the directory to which the user will have access (all of the subdirectories too), and permission-code is a number between 0 and 7 that defines what the user may do.
The permission-code is a bit-map where the three least significant bits each have a specific meaning. Here is a table:
1 -read and directory access
2 - create access
4 - overwrite and delete access
The protection bits are added together to create the permission-code. For example 3 (1+2) permit the user to read files and create new files but not overwrite or delete and existing file. A permission-code of 7 (1+2+4) would permit full access. Here are some examples:
guest * /public 3
brian xyzzy / 7
In these examples guest may log in with any password and may copy files or create new files in the directory /public while user brian must log in with password xyzzy but will be granted full access, e.g. read, write, overwrite, and delete, to all files in the system.
If you are running in a radio-based environment I would not give out the latter user/password combination because it will give anyone access to your entire disk. Also remember that the user/password combination are broadcast in-the-clear for anyone to read (if they have trace turned on). It is wise to segregate your radio-link users in a separate directory tree and not permit delete or overwrite access. That should prevent malicious mischief.
3.2.5. Configuring NET and the AUTOEXEC.NET file
Now you need to configure and run NET. Configuring NET to run may be performed manually every time you start up NET.EXE but that gets old pretty fast. There are usually many commands that must be typed the same way every time net is started. Fortunately Phil thought of this and provided the AUTOEXEC.NET file. The intention here is to place all the commands that you always execute in a file to be read and executed by NET.EXE whenever you start up. To this end you will want to edit the file AUTOEXEC.NET prior to running NET.EXE. Just use a text editor to enter the commands into the file AUTOEXEC.NET as you would type them at the "net>" prompt.
3.2.5.1. Setting the IP address
When NET.EXE first starts up you need to tell it about many things, i.e what comm ports you have, what your IP address is, what your host name is, what other systems you will communicate with, what services you wish to provide, etc. The first thing to do is to tell net who we are with the ip address, hostname, and ax25 mycall commands. Enter your ip address in dotted decimal notation or give the symbolic name from your HOSTS.NET file. Here is an example:
ip address [44.96.0.1]
The selection of an address is very important. If you are going to be part of a network you must have a unique address. Talk to the person in your area who is responsible for coordinating addresses. If you are not a part of the Internet and are just using this with your own computers, pick any unique address that suits you.
NOTE: Throughout this document names and IP addresses are interchangeable. Net differentiates between the two by requiring you to enclose IP addresses in square brackets [].
3.2.5.2. Hostname
The hostname command is used to set the name of your system. This is displayed when someone initiates an FTP session with your system. Again here is an example:
hostname wb6rqn.ampr
This corresponds to my system in my local domain. For the purposes of amateur packet radio your call sign followed by "ampr" (amateur packet radio network) is probably sufficient.
3.2.5.3. AX25 Mycall (packet radio only)
Since I also run net on the air (amateur packet radio networking) I must specify my amateur call sign with the ax25 mycall command. Again, here is the entry from my AUTOEXEC.NET file:
ax25 mycall WB6RQN-0
The call sign is entered in the same form that is used with the standard TAPR TNC software, e.g. the call sign is followed by the SSID field.
If you are going to run TCP/IP on the air using the ax25 driver (described below with the attach command) the ax25 mycall entry MUST precede the first attach command that uses the ax25 driver. Otherwise there is no required order for these commands.
3.2.5.4. Attach command
The attach command tells net about your comm ports and in what mode the ports will operate. Currently four types of comm hardware are supported: standard PC async comm adapters, the HAPN TNC board for the PC, the Eagle RS-232/2 card, and the 3Com Ethernet controller. Each of these devices has its own version of the attach command. Here is the attach command for an async adapter card acting as COM1:. You would use this to attach your pc to a TNC running the KISS code:
attach asy 0x3f8 4 ax25 ax0 1024 256 4800
This means attach an asynchronous adapter whose port address is 3F8 hex using interrupt line 4 (both standard for com1:), as an ax25 device (KISS TNC), using a buffer size of 1024 and a maximum transmission unit (the largest packet you are allowed to send) of 256 bytes, running at 4800 baud. The media name for this device will be ax0, a name that will be used in the route, connect, and param commands to refer to this comm port. This is probably a pretty good place to start. If you also wish to use COM2 instead of or in addition to COM1 you would add the line:
attach asy 0x2f8 3 ax25 ax1 1024 256 4800
If you are instead going to use COM2 to connect with another PC using a hard wired connection (some of us do have multiple PC's) you might want to use COM2: to connect to the other PC. We would want to use SLIP to do this so the attach command would be:
attach asy 0x2f8 3 slip sl0 1024 576 4800
NOTE: IBM-PCs and clones all use I/O port address 0x3f8 and interrupt request line 4 for COM1 and port address 0x2f8 and interrupt request line 3 for COM2. There are other comm cards that implement COM3, COM4, etc., but these cards may use non-standard port addresses and interrupt request lines for these ports. Check the documentation that came with your comm card if you are trying to use COM3 or higher.
If you have an HAPN TNC card for your PC you will want to enter the following attach command:
attach hapn 0x3f8 4 ax25 h0 1024 256 csma
This tells net to use an HAPN board with the port address 3F8h and interrupt request line 4. The speed of the board is determined by the board so the software has no control over that function. The last parameter, listed as operation.
Recently the Eagle RS-232/2 card has become available at very reasonable prices. This two-channel card generates HDLC frames directly and may be connected to a modem for direct packet radio operation without a TNC. Normally it would be connected to a Bell-202-type half-duplex asynchronous modem.
The attach command for the Eagle board is almost identical to that of the standard async comm card. Here is an example:
attach eagle 0x300 5 ax25 eg0 2048 256 1200
Two items must be as shown in the example: the mode must always be ax25 (not SLIP) and the media name must begin with 'eg' and end with a single digit. The first Eagle card must be called eg0 and the second must be called eg1.
The Eagle card is hard wired for a base address of 0x300 and IRQ5. The use of IRQ5 conflicts with the disk controller on the PC/XT (no problem with the PC/AT). If you wish to use the Eagle card with a PC/XT or compatible you will need to locate the trace from pin 3 of the 74LS125 (U12) to B23 (IRQ5) on the edge connector. Cut this trace at the edge connector and reroute it to B4 (IRQ2) on the edge connector. This will eliminate the conflict and allow you to use IRQ2.
If you happen to have more than one PC you may wish to connect them using an Ethernet. The net software supports the 3Com 3C500 or 3C501 boards for the PC. The command to attach this board is:
attach 3c500 0x300 3 arpa ec0 5 1500
This tells net that there is a 3Com 3C500 board at I/O address 300h using interrupt request line 3 with the media name ec0. Net should reserve five buffers and the largest Ethernet packet may be 1500 bytes long.
A word about the selection of the value for the maximum transmission unit. For standard TNCs and radios 256 is probably the largest value you should use. This ensures compatibility with the rest of the AX.25 community and ensures that you are legal if you are operating unattended (part 97 of the FCC regulations specifically mentions the AX.25 protocol in permitting unattended digital operation above 50 MHz). The smallest value you may use is 64. Performance improves with larger values IF you can get them to the other end without errors. I suggest you stick with 256 until you can run some experiments of your own. If you have a good transmission path and all the stations and gateways are attended, feel free to use larger values. It will result in improved performance (see the discussion of the mss and window parameters).
3.2.5.5. Param command
If you are using a TNC running the KISS code (you probably are if you are operating amateur packet radio) you will need to set the parameters in the TNC. This is accomplished with the param command.
There are five setable parameters in the kiss code. They are:
1. Transmitter keyup delay (TXD). This is how long the TNC will wait after keying the transmitter prior to beginning to send data. The proper value for this parameter is dependent on your configuration. This value is in 10's of milliseconds. Acceptable values range from 0 (0 ms) to 255 (2,550 ms or 2.55 seconds).
2. Persistence (p). This is the probability that the TNC will key your transmitter if a slot is found empty (the channel is free). Acceptable values range from 0 (p = (0+1)/256 = 0.4%) to 255 (p = 255+1/256 = 100%). The default value is 63 (25%). The optimum value is somewhere close to 1/n where n is the number of users on the channel.
3. Slot time (ts). This is how long that the TNC will wait between samples of the channel. Acceptable values range from 0 (0 ms) to 255 (2,550 ms or 2.55 seconds).
4. Tail timer (tt). This is how long the TNC will keep the transmitter keyed after the last character has been transferred to the HDLC controller. This has become an outdated command since most of the TNCs now set this value automatically based on data rate.
5. Full Duplex. A zero value (the default value) means operate the TNC in half-duplex CSMA mode (listen before you transmit). A non-zero value means transmit whenever there is data to send.
Let us assume that on the channel associated with ax0 that I have a radio that
requires a transmit keyup delay of 200 ms, I want persistence to be 20%
(p=0.2), and I want the slot time to be 160 ms. These are the values that we
use in the DC area and make us "good neighbors" who do not "hog" the channel.
I would enter the following commands:
param ax0 1 20
param ax0 2 51
param ax0 3 16
Note that the parameters are now specified as decimal values.
NOTE: The 'param' command will be used for issuing other device dependent commands as the need arises. Right now it is used only for setting the parameters for kiss TNCs and the speed of SLIP and AX25 links. Other versions of the 'param' command will be added as the need arises.
If you are dealing with a SLIP link (you used the entry slip instead of ax25 in the attach command) the param command is used to change the speed (baud rate) for the line. If you wanted to change the speed of your second slip link to 4800 baud you would enter:
param sl1 4800
3.2.5.6. ax25 digipeat command (packet radio only)
If you are currently an active digipeater in your area you can also make your system continue to be a digipeater for those poor souls unlucky enough to still be running ordinary AX.25. The command for this is:
ax25 digipeat on
3.2.5.7. Mail Gateway
The mail subsystem (SMTP) needs to know where to send mail should the destination be unknown to the sending system. This is handled by the gateway command as follows:
smtp gateway wa3pxx
- or -
smtp gateway [44.96.0.13]
Should you try to send mail to a host that is not in your HOSTS.NET file the mailer will route the mail to the system specified in the gateway entry. This presumes that the gateway system is smart enough to figure out to whom the mail is addressed so that the mail can be forwarded. At this time the mailer in NET.EXE is not "smart" enough to act as a mail forwarding node. This field is only here should you be lucky enough to have another computer accessible to you with a smart SMTP mailer or another host that acts as a gateway to another network. Any UNIX 4.2 or 4.3 BSD system has such a mailer. A PC running the WA3PXX BBS gateway also will serve.
For packet radio enthusiasts another use for the gateway command is to send mail on to your local BBS gateway station. Bob Gibson, WA3PXX, has constructed a gateway program that will permit the transfer of mail from the WA7MBL BBS to SMPT and back again. By having your local BBS run DoubleDos with the WA7MBL BBS in one partition and NET in the other you can automatically move mail between the two domains.
3.2.5.8. Construction of Routing Tables
Now you need to construct the routing table. This table is used by the IP to determine how to forward your packets. Each entry consists of two or three parts, the IP address of the destination, the link upon which it is to be forwarded, and the IP address of the next station in line if there can be more than one IP address on the link (used if the mode is ax25 and not used if the mode is slip). Here are three sample entries, one for a station more than one hop away via ax25 to be forwarded by 44.96.0.7, one for station one hop away on ax25, and one for a station on the other side of a slip link:
route add [44.96.0.5] ax0 [44.96.0.7]
route add [44.96.0.2] ax0
route add [44.96.0.12] sl0
route add n3ja ax0
The first string following the command 'route add' is the destination IP address. The second field, i.e. ax0 or sl0, is the media and must match up with one of your previous attach commands. The last field is the next station in the path if the destination is more than one hop away. This is an optional field and only needs to be used if the media is a broadcast media such as Ethernet or AX.25 and the destination is more than one hop away.
Note that the address may be specified as either an IP address in dotted decimal notation or it may be a symbolic address from your hosts.net file. If you choose the latter technique you must enter the symbolic address precisely as it was entered in the hosts.net file, e.g. upper and lower case characters in the name are significant.
If you are using an Eagle RS-232/2 board your media is named eg0 or eg1. There is still a problem because there are two ports on the board. In order to solve this problem you will need to add the letters 'a' or 'b' to the media name. For instance, if you have a single Eagle card your media names become 'eg0a' and 'eg0b' for the A and B ports of the card respectively. Remember, take the media name from the attach command and append either A or B to the end of the name to select the appropriate port. Here are some examples:
route add [44.96.0.22] eg0a
route add aj9x eg0b wb3ffv
There are two other special types of route entries; the default entry and a cluster entry. Here is a default entry:
route add default ax0 [44.96.0.99]
This means that if the address does not match any entry in your table, route the packet to 44.96.0.99 via ax0. Hopefully the switch at 44.96.0.99 will be able to forward the packet to its destination. This generally works well if you are merely an end node (a leaf) in the network and all your traffic goes to a single gateway.
3.2.5.8.1. Cluster Routing and its Associated Concepts
The other option for routing is cluster routing. It allows you to send blocks of addresses in a certain direction. This is useful if all the users in a given area have some common part to their IP addresses. Here is an explanation of cluster routing and addresses in general.
The IP address is thirty-two (32) bits long. It is generally represented as four 8-bit numbers, with each number being written in decimal form. For example, my IP address is 44.96.0.1. This number can be represented as the hexadecimal value 2C600001 or 00101100011000000000000000000001 in binary. We can break this out as follows:
decimal 44 96 0 1
hexadecimal 2C 60 00 01
binary 00101100 01100000 00000000 00000001
Normally when you make an entry in the routing table, all bits of the address are significant, e.g. an exact match is needed for the address to be recognized. On the other end there is the default route in which any address matches.
Cluster routing falls somewhere between these two extremes. Cluster routing allows you to specify how much of the address is to be considered valid. In order to determine how many bits in the address are valid you enter the address in a special format:
route add [44.96.0.64]/26 ax0
This means that only the first 26 bits of the address are to be considered significant. This is a form of wild card for the address. Here is that address in binary to show the mapping:
00101100 01100000 00000000 01??????
The question marks in the above address show the least significant six bits being "wild," or matching any corresponding bits in the address. Here are some examples:
44.96.0.67 00101100 01100000 00000000 01000111 (a match)
44.96.0.89 00101100 01100000 00000000 01011001 (a match)
44.96.0.01 00101100 01100000 00000000 00000001 (no match)
This works because the routing process in the net code will, when presented with an address, search for an exactly matching entry. Failing to find that it will then look for an address that matches on the most significant 31 bits, then 30 bits, and so on. If presented with the address 44.96.0.67 IP would, after 6 tries, match the address to the example given above.
By judiciously assigning addresses we can make the address aid us in routing the packets. The users within a LAN should have something in common in the high order part of the address so that we can use a single entry in the routing table to make things go in the proper direction. Here in the Washington DC area all addresses begin with 44.96.0. This identifies this general area and may be used to provide routing to us. Once the packet arrives in our general area cluster routing is then used to further route the packets to the appropriate area. In DC and the parts of Maryland immediately surrounding DC the low order byte ranges from 0 to 63. Northern Virginia users get numbers in the range of 64 to 127. The Baltimore users get 128 to 191 while the Harrisburg, PA, users get 192 to 255. The idea being that we can use the top two bits in the low order byte of the address to identify LANs within the address. That way the bits in the high order part of the address will get you into the general area, the next part of the address will get you to the proper LAN, and the least significant bits will get you to the proper host or user.
3.2.5.9. Routing Loops and the Time Too Live (TTL) Command
It is quite possible (and likely!) to make errors when setting up routing tables that will cause a routing loop to occur (a routing loop is a circular path that never reaches the intended destination). Imagine what would happen if two stations had their default routing pointing at each other like this:
In this case a packet that got routed using the default route would bounce back and forth between the two stations forever. There is a command that can prevent this from going on forever: the Time-To-Live (ttl) command. Every IP packet has a ttl field in it that is decremented by 1 at every hop. When the ttl field reaches zero and the packet is not at the destination the packet is discarded and an ICMP message explaining the fact is sent to the sending host. Normally net sets the ttl field to 255. If you know that no host is more than 5 hops away you might issue the following command:
ip ttl 5
This means that all packets from your host/station are sent with ttl set to an initial value of 5. These packets will now be discarded if they haven't reached their destination after 5 hops. This limits the traffic in the network should somebody inadvertently create a routing loop.
3.2.6. Using Digipeaters and the ARP Add Command (packet radio only)
Since there may not be many TCP users in your area you may need to use a digipeater (or two) to reach the other users in your area. This is now possible by adding entries to the ARP (Address Resolution Protocol) tables. ARP serves to map IP addresses into Ethernet or AX25 address, whichever is appropriate to the media in use. ARP normally does its work automatically by directly conversing with the other station but it cannot do that if the other station is reachable only via a digipeater. In that case you must "hard-wire" an ARP table entry with the ARP ADD command.
Before you can use the ARP ADD command you must know the path to the other station. Let us assume that the station with whom you wish to communicate is WA4OIE (Other Internet Experimenter) whose address is 44.96.0.247, but the only path available is via WB3PID (Poor Inefficient Digipeater). In this case you will use the following ARP ADD command:
arp add [44.96.0.247] ax25 wa4oie wb3pid
- or -
arp add wa4oie ax25 wa4oie wb3pid
From this point on packets sent over an AX25 link to address 44.96.0.247 will use the AX25 destination address of WA4OIE with an intermediate digipeater address of WB3PBD. If you need to use more than one digipeater it is permissible. Just place the call signs of the digipeaters sequentially following the destination AX.25 address.
3.2.7. Window and Maximum Segment Sizes
The next information we want to include is some information used by TCP to determine how much data it can send at one time and how much data may be outstanding before it stops to wait for an ack from the other end. Here are the example values:
tcp mss 216
tcp window 648
The parameter mss stands for maximum segment size and represents the largest single segment that TCP will send. Mss should be set as a function of the quality of the link over which you are running. Relatively error-free links should use larger values of mss. If you are running on amateur packet radio and wish to operate unattended you should probably limit this value to 216 (an mss of 216 will cause you to send AX.25 packets that are 256 bytes long.
The net program now compares the mss value and the mtu values given in the attach command for the media being used. Since TCP and IP each have a 20 byte header (a total of 40 bytes), an mss of 216 corresponds to an mtu of 256. If you are using mixed mtu's, i.e. 256 for AX.25, 1500 for Ethernet, and 576 for SLIP, set the mss to correspond to the largest mtu you are using and let net adjust the mss downward for the media that are using smaller values for mtu.
The 'window' parameter is how many bytes may be outstanding at any one time before you wait for an ack. If you have a pretty good link you can increase the value of mss. If window is larger than mss TCP will run as a sliding window protocol, e.g. continue to send packets while waiting for ACKs on previously sent packets. Since TCP uses selective reject (resend ONLY those segments that were damaged or lost) this is not a very expensive proposition. In any case window should always be a multiple of mss to prevent the transmission of small packets every once in a while.
If you are running on a radio channel at 1200 baud remember that a 1024 byte transmission will take seven seconds, a time that can make you unpopular if you have to share the frequency with AX.25 TNCs that cannot adapt to the high channel utilization. In those cases it is probably better to reduce window and/or mss values. The above values will make you fit in reasonably with your other AX.25 neighbors. Remember that the efficiency of large packets and long transmissions are probably not worth having your neighbors so angry that they tie a rope between your coax and the bumper of a pickup truck so that they can non-surgically remove your station from your shack.
One last point before we move on; the mss and window values that you set will be the ones that your TCP will ask the OTHER station to use. When the session is initially set up the two TCPs will exchange mss and window values. This permits stations to automatically adjust to the capabilities of the other station. For this reason it is best to get everyone in your LAN to use the same values.
3.2.8. Starting the Servers
Next you need to decide what services you will provide to other users in the network. You must start the servers or others won't be able to make use of your system for mail or file transfers. You will simply be a switch for other users (in fact, for a switch on a hill that may be just what you want). You will still be able to initiate file transfers or telnet sessions but no one will be able to initiate one with you. Should you fail to start the servers anyone trying to access those services on your machine will just receive a "Closed, (reset)" message. For the sake of consistency you will probably want to use the start command to enable the following services:
start telnet
start ftp
start smtp
start echo
start discard
Telnet is the terminal-to-host and terminal-to-terminal mode, ftp is the file transfer protocol, smtp is the mail system (simple mail transfer protocol), and echo is the echo server (it just sends back any packets it receives -good for finding out if a switch is out there and running). The discard server simply throws away anything it receives. The echo and discard servers are generally used for testing a link.
3.3. Running the network program NET.EXE
Start the networking program running by issuing the command "net." You should be rewarded by having the "net>" prompt appear on your screen. If you prepared AUTOEXEC.NET as described in the previous section then you don't need to issue any configuration commands. If you have not set up AUTOEXEC.NET you will want to read that section of the manual prior to proceeding with this section.
3.3.1. Operating Modes
Net provides two modes of operation: command and session. In the command mode you are interacting with the command interpreter to permit you to establish sessions, retrieve status information, establish new routing table entries, etc. Please consider the commands you were required to enter in the AUTOEXEC.NET file. All of those commands were directed at the command interpreter. You can tell that the NET.EXE command interpreter is waiting for input because it will present this prompt:
net>
The session mode is unique to the session with which you wish to communicate. TELNET (terminal-to-host and terminal-to-terminal) and FTP (the File Transfer Protocol) are the two types of sessions with which you may interact and each has its own sets of commands and operating modes.
Before you get too carried away with trying things it is probably a good idea to read at least as far as the discussion on multiple sessions. That will explain how to start and use TELNET and FTP as well as how to keep straight all the activity from multiple users.
3.3.2. Running TELNET
TELNET is used to provide terminal mode access to a host computer system but may also be used to have a terminal-to-terminal "chat" with another operator. There are three commands directly associated with the TELNET service: the 'telnet', the 'eol', and the 'echo' commands. ,NH 4 The 'telnet' command:
The 'telnet' command is used to establish a TELNET session with a remote TCP socket, usually the TELNET server on a remote host. To establish a TELNET session you would issue the 'telnet' command as follows:
telnet wb2sef
telnet [44.96.0.2]
Both of these commands would establish a TELNET session with the TELNET server at WB2SEF because WB2SEF is defined in HOSTS.NET as having the address 44.96.0.2. Note that we merely specified that we wished to establish a TELNET session and the TELNET client then connected us with the TELNET server which resides at TCP port address 23. There is an extended syntax for the 'telnet' command that will let you specify the port number at the remote host to which you wish to be connected. Here is an example of the extended syntax:
telnet [44.96.0.2] 7
telnet wb2sef 9
In the first example TELNET is being asked to establish a session with port number 7, the echo server, at the host whose address is 44.96.0.2. The second example also is a request to connect to the host whose address is 44.96.0.2 but this time the connection is to be made to port number 9, the discard server. These two ports are regularly used for test purposes, the echo server echoing back everything it receives and the discard server discarding everything it receives but returning a proper acknowledgement.
Once you have issued the 'telnet' command you will see the message "SYN sent" followed a short time later by the message "Established" (assuming that your destination was reachable). At this point you would be in communication with the TELNET server on the other end. If the remote host is a timesharing computer (possibly running UNIX) you would very shortly be presented with a login screen. You may consider your keyboard and screen to be directly connected to the remote computer at this point.
On the other hand maybe you were attempting to establish a connection with another computer running the net code. In that case you would be in keyboard-to-screen communication with the operator at the remote host (assuming that he/she selected the new session as the current session; a subject that will be discussed later). Whatever you type will appear on the other screen and vice-versa.
3.3.2.1. The ECHO Command
In addition to the 'telnet' command there are the 'eol' and 'echo' commands. The 'echo' command determines what the TELNET client will do if the remote host offers to echo characters (what we would consider full duplex). Here is the command syntax:
echo accept [the default value]
echo reject
If the remote host is a timesharing computer you probably want it to echo your characters back to you rather than let your local TELNET client echo the characters. This permits you to use sophisticated screen-oriented programs without having your local echoing disrupt the screen display. On the other hand you may prefer to reject echoing in the case of a very slow network where having what you type appear on the screen several seconds later could be very annoying. Please note that the setting of this parameter has no effect when entering a TELNET session with another copy of NET since NET always refuses to echo characters.
3.3.2.2. The EOL Command
The 'eol' command is also used to adjust the keyboard functionality when remote echoing has been negotiated. It is used to select the appropriate end-of-line character to be sent when the operator presses the <ENTER> or <RETURN> key. Here are examples of the two options:
eol standard [the default value]
eol unix
Should you set 'eol' to 'unix' and remote echoing is negotiated by the two systems, the <RETURN> or <ENTER> key will send an ASCII line feed character rather than the carriage return character. Normally this will not be needed but some UNIX system demand this. Should the remote host not respond to your <RETURN> key you might want to try this option.
To exit back to the command prompt from within a telnet session press the F10 key. The 'net>' prompt will appear. This does not close the TELNET session but merely suspends it. Incoming data addressed to your TELNET session will be saved until you re-enter the session (see the discussion of changing sessions that follows later).
The last item of interest to the TELNET user is how to terminate a TELNET session. That is accomplished with the 'close' command. To close the session simply press the F10 key to return to the command prompt and enter the 'close' command. You should be rewarded with the sequence of messages:
FIN wait 1
FIN wait 2
Time wait [followed by a delay period of about 30 seconds]
Closed (Normal)
3.3.3. File Transfer (FTP)
The File Transfer Protocol (FTP) permits you to send and receive both text (ASCII) and binary (image) files. The FTP application accepts many commands that will permit you to create files, delete files, change directories, and copy files. This section will guide you through the most used FTP commands.
3.3.3.1. Establishing a Session
To establish an FTP session with a remote host you use the 'ftp' command. To establish an FTP session with WB2SEF I would use one of the following commands:
ftp wb2sef
ftp [44.96.0.2]
Both commands do the same thing because of the information contained in my HOSTS.NET file. After issuing one of the above commands you would see the usual 'SYN sent' and 'Established' messages. You would then be greeted by a message from the remote FTP server that looked something like this:
220 wb2sef.ampr FTP version 871225.5 ready at Tue Jan 19 17:57:23 1987
This message tells you that the remote FTP is ready to accept commands from you. FTP gives you no prompt so at this point you must understand that after issuing a command you will be notified of the command's completion but no further prompting for messages will occur. One thing to note is that when FTP sends you a message it will always be prefixed with a three-digit number. This is for the benefit of computer programs that may be driving the FTP system. The number is for the benefit of the computer and the text is for the benefit of the user.
The first thing you will need to do is to log in to the remote host with your user ID and your password. Unless you have been given a specific user ID and password by someone at the remote host you will probably log in with the guest user ID and password. You will send the 'user' and Here is an example:
user guest
331 Enter PASS command
pass xyzzy
230 Logged in
This exchange presumes that your user ID is "guest" and that your password is "xyzzy." If the user ID does not require a password you may or may not be prompted for the password. NET always prompts for the password whether it needs it or not. If the remote host is running NET and has in its FTPUSERS file an entry that uses an asterisk (*) for the password, any password will be accepted.
If you enter either an invalid user ID or an invalid password the remote FTP will return the following message:
550 Permission denied
Simply reenter the 'user' and 'pass' commands with the proper values and you will be logged in. You may also enter new 'user' and 'pass' commands at any time to change your user ID and hence your permissions as far as the remote host is concerned.
3.3.4. Manipulating Directories on the Remote Host
When you log into the remote host you will be set in "your" directory (I put the word your in quotes because many people may be using that directory since many people may be allowed to log in concurrently with the same user ID). You can get a directory listing of files within that directory with the 'dir' command (just like DOS). What you will receive back from the remote host will be a standard DOS directory listing. If you would prefer a short listing, e.g. only the names of the files, you can use the 'ls' command. Both commands will accept wild cards so the following commands are all valid:
dir
ls *.*
dir *.com
ls test*.dat
After issuing the command you will see the following sequence of responses from the remote host:
200 Port command okay
150 Opening data connection for LIST /public
Your directory listing will be displayed here
Get complete, nnnn bytes received
226 File sent OK
The end of the "150 Opening data connection ..." response will differ depending on the directory request you made. If you used the 'dir' command you would see the word "LIST." If you used the 'ls' command you would see the word "NLST." What followed the "LIST" or "NLST" would be the name of the directory you are listing.
In addition to listing directories you can change the directory and query for the current directory. Let us assume that for your user ID (guest) your root directory is /public. Let us also assume that in public you would find the three subdirectories tcp, games, and utils. When you log in your directory is set to /public. Now you issue one of the following commands:
cd tcp
cd /public/tcp
The result would be the same since you were already in directory /public. FTP would then send you the response:
257 "/public/tcp" is current directory
You may use the 'cd' command to change directory to any subdirectory below your home directory in the same way that the DOS cd command will also allow you change directories.
If you are not sure what directory you are in you may use the 'pwd' (print working directory) command. If we were to issue the command:
pwd
the remote FTP would then respond:
257 "/public/tcp" is current directory
as if you had just changed directories.
Now we get down to the meat of the matter: sending and receiving files. Prior to doing a file transfer you need to tell FTP what type of transfer to use. You have two choices: ASCII (text files) or Image (binary files). To select what type of transfer, you use the
type i
type a
The former will set all subsequent transfers to image mode for sending binary files. The latter will set all subsequent transfers to ASCII mode for sending or receiving text files. If you use the 'type' command by itself like:
type
FTP will respond with either the word "Image" or "Ascii," whichever is appropriate. If you do not specify a type of transfer FTP will use the default value "ASCII."
Files transferred with type set to ASCII will have their newline sequence translated to that expected by the remote host. Files transferred with type set to image will have no translation performed at all. All bytes in the file will be transferred with no changes whatsoever.
Once you select the type of transfer you desire you may then send or receive files. The 'put' and 'get' commands are used to send and receive files respectively. Let us assume that I have a file on my system in my current directory called "foo" and I want to transfer it to the remote host and have it placed in my current directory there. To do this I would use the following command:
put foo
FTP would then transfer file "foo" from the local to the remote system. You would know the status of the transfer from the following sequence of messages:
200 Port command okay
150 Opening data connection for STOR foo
Put complete, nnn bytes sent
226 File received OK
Now let us fetch file "bar" from the remote system. Here is your command the the responses from FTP:
get bar
200 Port command okay
150 Opening data connection for RETR bar
Get complete, nnn bytes received
226 File sent OK
Now it may not be convenient to have the file retain its file name when it is copied. Perhaps there is already a file with the same name at the destination and you do not wish to, or may not be permitted to, overwrite the file. In that case you would add the destination file name to the get or the put command as follows:
put foo bar
get /public/tcp/herfile herfile
In the first example the local file "foo" would be copied to file "bar" on the remote system. In the second example the file "/public/tcp/herfile" would be copied to "herfile" on the remote system. The reason for doing it this way in the second example is to avoid having FTP try to create the file "/public/tcp/herfile" on the remote end. Perhaps there is no directory "/public" or "/public/tcp" or perhaps you are in an FTP session with a system that has completely different file naming conventions (remember that you may be communicating with systems other than PC's).
It is also possible to get a file and type it to your CRT directly. If you want to get the file to your screen use "con" as the name of the destination file. Here is an example that will fetch file "foo" and send it to the CRT:
get foo con
You may at some point want to terminate a transfer that is currently in progress. The 'abort' command is used for this. There are no parameters on the abort command. Just type 'abort' and the current transfer will be aborted.
The last command of interest to FTP users is the dele command. The dele command is used to delete a file on the remote system. Here is an example that will delete the file foo on the remote system:
dele foo
Remember that in order to use the dele command you must have delete and overwrite permission on the remote system.
When done using FTP use the command 'quit.' 'Quit' will get you the following message sequence:
221 Goodbye!
Close wait
Last ACK
Closed (Normal)
All of this indicates that FTP has properly terminated the session and returned you to the command interpreter. Alternatively, you can just close the session by hitting F10 and typing "close".
3.3.5. Multiple Sessions
One of the many advantages of NET is that it permits you to establish several sessions concurrently. For instance, you could establish an FTP session with a host and then switch back to the command interpreter so that you could start another session. The nice thing about this is that it in no way interferes with any sessions that are already running. Your FTP session continues to transfer data even while you enter into a TELNET session with the same or a different host. Any screen output that arrives for a session that is not the currently selected session will be held until you again select that session. This prevents you from losing any output while you interact with another session or with the command interpreter.
As mentioned, in order to start a new session (or issue any other type of command for that matter) you must be interacting with the command interpreter. To get to the command prompt you need only press F10. Once at the command prompt you can examine or select a new session using the 'session' command (abbreviated 'se').
The session command when used by itself will give you a list of all the currently open session. Here are two examples:
session
se
The result will be a display similar to the following:
# &CB Type Rcv-Q State Remote socket
0 c7a8 Telnet 0 Established w3fws:23
*1 c434 FTP 0 Established 44.96.0.13:21
The first field (#) is the session number. The asterisk (*) identifies the current session. CB is the protocol control block associated with this session (these are explained in detail as part of the tcp status and ax25 status commands later in this document). The Type field identifies the session as an FTP, a TELNET, or an AX.25 connected mode (TNC) session. The state field indicates the state of the "connection" as far as this session is concerned. A value of SYN Sent indicates that the "connection" is in the process of being constructed. A value of Established indicates that the "connection" and therefore the session is open and ready to transfer information. Values of FIN Wait 1, FIN Wait 2, or Time Wait indicate that the connection is being closed. The last field, Remote Socket, identifies the host and port with whom the session was initiated.
Once you start a session it becomes your current session unless you close it or switch to another session. To get back to a session from the 'net>' prompt all you need to do is press the <RETURN> or <ENTER> key. If you happened to close the current session there will be no current session. In that case pressing <RETURN> or <ENTER> will have no effect. You will need to explicitly select a new session with the session command.
If you follow the session command with a number, the session command will make the session whose number was specified, the current session and then turn control of the keyboard and screen over to that session. Here are two examples:
session 0
se 0
Both of these examples change the current session to session 0. At that point you will be interacting with the desired session.
As mentioned in the section on the 'telnet' command you close a session with the close command. If the session you wish to close is not the current session you need to issue the command 'close n' where n is the number of the session you wish to close.
Last of all you may need to abort a session or an open socket. This may occur when you have a session with another host and that host goes away for whatever reason (power failure, hardware failure, link failure, etc.). In that case you must resort to the 'reset' command. The without having to go through the normal closing sequence. There are two forms. The first is the command or 'ax25 reset' followed by the address of TCP or AX.25 control block, as appropriate. Here are several examples:
tcp reset c7a8
reset 0
Either command would force TCP to close the socket associated with the session with 44.96.0.13 and hence close that session. It would give no indication to the other end that the socket had been closed. The only indication that the other end would receive would be to receive a reset instead of an ACK packet the next time the remote end sent a packet of data.
3.3.6. Status Monitoring and Other Commands
There are quite a few commands in NET.EXE. Many of them were explained in conjunction with the installation instructions and, in fact, have little use beyond initialization. Commands in this category include:
ip address setting your IP address
ax25 mycall setting your AX.25 link address
ip ttl initial time-to-live field for IP packets
attach starting a driver for a particular hardware device
tcp mss setting the maximum size for a TCP segment (packet)
tcp window setting the maximum number of un-acked bytes
ax25 digipeat enable/disable AX.25 digipeating
hostname set the name for your system (used by FTP)
On the other hand there are quite a few commands that you will be using extensively. Let's start by covering the status commands.
3.3.6.1. Getting Status Information
3.3.6.1.1. ip status
The first of the status commands is 'ip status' and may be abbreviated 'ip s'. This returns information about the status of IP packets that have passed through your system: e.g. originated, received, or passed through (switched). The format for the ip status response looks like this:
total 973 runt 0 len err 0 vers err 0 chksum err 5 badproto 0
The 'total' field (973 in this case) identifies the number of IP datagrams that have passed through your system. The next field, 'runt', identifies the number of packets that were below minimum acceptable size. 'Len err' identifies the number of packets with length errors. 'Vers err' identifies packets that came from a system running a version of IP that is incompatible with the one that you are running (unlikely to occur unless the Internet adopts a new standard for IP). 'Chksum err' is the number of packets that arrived with a checksum error on the IP header (these packets will be discarded because the system has no way of knowing if any of the information is valid). 'Badproto' identifies the number of packets that arrived with the protocol identifier set to an upper layer protocol (ULP) that is not either ICMP, TCP or UDP (the only three ULP's currently supported in NET.EXE).
Of all these possible errors you are likely to see only the runt, len err, and chksum err fields increment. Version and bad protocol errors can only occur if you are communicating with a system that supports a different version or a different set of ULP's. This is unlikely to happen.
3.3.6.1.2. tcp status
Another often used command is the tcp status command. tcp status returns a great deal of information on the current status of your TCP "connections." Upon entering the command 'tcp status' (abbreviated 't s') the system will print a General status on the TCP activity and an abbreviated display on the status of each TCP session. The top line looks like this:
Conout 5 Conin 17 Reset out 2 Runt 0 Checksum err 1 bdcsts 0
at your system while 'conin' is the number of incoming "connections" that have been made with your system. 'Reset out' is the number of resets that were sent to remote systems (this would happen if a remote system attempted to send data to a socket that had been closed). The 'Runt' field is the number of undersized packets that were received. The 'Checksum err' field is the number of TCP segments that were discarded because the segment failed the TCP checksum check (IP checksums only the packet header while TCP applies a checksum test to the entire TCP segment including header). The last field indicates the number of broadcast messages that have been received.
Following the header line a table is presented, one line per socket. The headings appear as follows:
&TCB Rcv-Q Snd-Q Local Socket Remote Socket State
f784 17 0 44.96.0.1:1001 44.96.0.2:23 Established
eb30 0 0 44.96.0.1:23 0.0.0.0:0 Listen (S)
In the above example there are two open sockets. The first, associated with the TCP Control Block (TCB) at address f784, is a TELNET (terminal-to-terminal or terminal-to-host) session with the system whose address is 44.96.0.2. The second socket, described by the TCB at location eb30, is a passive ("server") open that exists to accept incoming TELNET connections. Now for a more comprehensive description of the fields.
The TCB is the TCP control block. The number, in hex, is the address of the TCB in memory and serves to identify a particular open socket. Rcv-Q is the number of octets (8-bit things that we normally call bytes) that have been received and are waiting to be processed (this is one way to tell if you have received information from another station if you are involved in more than one TELNET or FTP session).
The next two fields, Local Socket and Remote Socket, make up the identification of the connection as far as TCP is concerned. The first part of a socket number is the IP address. The second part of the socket number, the part following the colon, is the port number. There are many "standard" port numbers in use. Here are some of the more common:
Port Application
7 Echo server
9 Discard server
20 FTP server data port
21 FTP server command port
23 TELNET server
25 SMTP server
You may see other port numbers used such as 1001, 1002, etc. These are temporary ports that are used to form a unique connection (TCP identifies a connection by combining the remote and local socket address in order to guarantee uniqueness).
Since no two systems have the same network address the combination of local socket (address + port) and remote socket forms a unique combination. This is how the TCP on both ends of a "connection" identifies that connection.
It is possible to get even more information about a specific socket by adding the TCB address to the end of the tcp status command like this:
tcb status f784
This will return the detailed TCP status information about the socket that is described by the TCB at address f784 (you get this address from the tcp status command without a parameter). Here is the sample format:
Local: 44.96.0.1:1001 Remote: 44.96.0.2:23 State: Established
Retry 0 Timer stopped Smoothed round trip time 5500 ms
The 'Init Seq', 'Unack', 'Next', 'WL1', and 'WL2' fields have to do with TCP's internal flow control and sequence numbering mechanisms. Continuous monitoring of these fields gives you a good idea of the performance of the network in terms of the number of packets lost. The 'Wind' field shows the number of bytes that the receiver is ready to accept, as of the last TCP packet received. The 'effective window' (the number of bytes that the transmitter may send) is the 'Wind' value reduced by the number of bytes "in the pipe", that is, already sent but not yet acknowledged. This is found by subtracting the 'Unack' value from the 'Next' value.
TCP often defers transmitting when it theoretically could, i.e., when there is data on the send queue and a non-zero effective window. This is done when there is already data "in the pipe" but there is not enough new data to fill a maximum size packet. In this case, TCP waits for an acknowledgment for the data already sent before sending more. This results in a stream of a few relatively large packets instead of many small packets ("tinygrams"), for a considerable efficiency improvement.
NOTE: A good understanding of sliding window protocols is required to make use of the information presented in these particular fields and a complete explanation is beyond the scope of this document. See RFC-793 or MIL-1778 for more details on the specific sliding window algorithms used in TCP, and RFC-896 for the "tinygram avoidance" transmission strategy.
The 'MSS' field displays the maximum segment size; the maximum number of bytes that may be sent as a single TCP segment (packet).
Both the maximum window size and MSS are "negotiated" by the TCPs running in the two communicating system. Essentially this means that the two ends "agree" on the best values to use for these parameters. When you set a value for window size and a value for MSS in your machine, those values are communicated to the remote end when a socket is opened. That allows the remote end to know how much information you are prepared to accept and to prevent the remote end from sending you too much information. Remember, the values for window and MSS that you set on your system will be the values that the other station will use when sending to you. Also remember that the two ends may set different values and still work effectively.
As an aside, you are permitted to change the value of MSS or WINDOW while the net program is running. On the other hand, changing the value of MSS or WINDOW after a socket has been opened will have no effect on any currently open sockets. Open sockets will continue to use the value for MSS that they negotiated when the socket was opened. The changed values will be used when TCP opens a new socket.
The Queue field indicates how many bytes of data are waiting at a particular socket. In the case of the send queue this field indicates the number of bytes transmitted but not yet acknowledged. During SMTP and FTP sessions it is not unusual to see this value equal to the window size. In the case of the receive queue the value indicates the number of bytes that have been received but have not been "picked-up" by the application.
The Total field indicates the number of bytes that have been received or transmitted on a socket since the socket was opened. This information is very useful during an FTP session because it will tell you the total number of bytes transferred on the file (FTP opens a new data socket for every transfer, closing the socket when the transfer is complete). If you know the size of the file ahead of time you can use this information to determine how much of the file has reached the receiving end -nice information to know when doing a long file transfer over a slow or unreliable link.
The next field is the retry counter. If a segment is not acknowledged within an appropriate period TCP will retransmit that segment because it will assume that the segment was lost somewhere in the network. Each time it retransmits a segment the 'Retry' counter is incremented. TCP never gives up sending data. It does 'back off' and send segments less and less frequently in order to reduce network loading.
The next field is the 'Timer' field. It displays the status of the timer for this particular socket. If TCP is waiting for an acknowledgement to an outstanding segment there will be a time displayed in this field. If there are no outstanding segments the word "stopped" will indicate that the timer is not running.
The last field, 'round trip time', is a very interesting piece of information. It is the amount of time that TCP has determined that it takes for an outgoing segment to arrive at its destination and for its acknowledgement to return. This value is used to determine the proper setting for the retry timer thus allowing TCP to adapt to the changing conditions of the underlying network and to prevent the network from being flooded by unnecessary retransmissions.
The tcp status command is probably the most used command in the net program. Don't be afraid of it, use it! You may not understand all the fields but you will quickly pick up what is important and what you can ignore. Experiment with it so that you understand it better. It is a key to pinpointing network performance problems.
3.3.6.2. udp status
The next status command of interest is 'udp status,' used for getting status information about information that has been received for the User Datagram Protocol (UDP) ULP. This command may be abbreviated 'u.' When an application makes use of the UDP transport service it opens a UDP socket. The udp status command will display the status of the transport service and of each of the
open sockets. Here is an example of the output of a udp status command:
In this example the 'sent' and 'rcvd' fields indicate how many UDP datagrams have been sent and received respectively. The 'bdcsts' field identifies the number of broadcast datagrams that have been received. The 'cksum err' field indicates how many datagrams have been received with errors while the that were addressed to unknown (unopened) sockets.
Following the general information is the specific information about all of the currently open sockets. Each open socket is identified by the address of its UDP Control Block (&UCB). Following that is the number of bytes that have been received and placed on the receive queue (Rcv-Q). Last comes the actual socket identifier consisting of the IP address concatenated with the port number.
3.3.7. AX.25 connected mode operation
In addition to the TCP/IP mode of operation this new version of NET.EXE now supports fully connected AX.25 (TNC-to-TNC) operation for talking to BBS'es and your buddies without TCP/IP. When NET.EXE is running you are free to establish both TCP and AX.25 sessions. When you make an AX.25 connection it will be treated like a TELNET session. You can use the session command to switch between sessions at will. This prevents the output from one AX.25 session from interfering with other sessions. To make a connection you use the connect command which is very similar to the TNC's connect command with the exception of the addition of a channel identifier. Here are some examples:
connect ax1 wa3pxx
connect ax2 n4qq k3af-10
The first command starts a connection to wa3pxx directly over the channel labeled ax1 (see the attach command). The second example establishes a connection to n4qq via the k3af-10 digipeater on channel ax2. To disconnect you use either the disconnect command or the close command.
The other commands for AX.25 are very familiar to a user of a TNC. Here is a list of commands and a brief description of their meanings:
ax25 digipeat [on|off] turn digipeating on or off
ax25 maxframe [n] set the maximum number of outstanding frames (packets) to n where n is between 1 and 7 inclusive.
ax25 mycall [<call>] Set the call sign for AX.25 frames
ax25 paclen [n] Set the maximum size of an AX.25 I-field
ax25 status Display a status much like tcp status. If you follow it with an ACB address it will display detailed info about a particular connection.
ax25 t1 [n] Displays or sets the value of the retransmission timer (FRACK). The value is in seconds.
ax25 t2 [n] Displays or sets the value of the ack delay timer (RESPTIME) in seconds.
ax25 t3 [n] Displays or sets the value of "keep alive" timer (CHECK) in seconds.
ax25 window [n] Displays or sets the number of bytes that may be on the AX.25 receive queue before the host begins sending RNR frames.
3.4. Using connected mode AX.25 for moving IP datagrams
Since connected mode AX.25 is now supported these connections may be used for both host-to-TNC (chatting with your TNC-only equipped buddy or with the BBS) and for connected mode IP channels. With IP you have your choice of "unconnected" or "connected" packets. The command that controls this is the mode command. The mode command allows you to select which style of connection will be used on a particular interface. Here are two examples:
mode ax0 vc
mode ax1 datagram
In the first example the interface named ax0 will use "connected" mode AX.25. This can improve the link reliability and hence throughput when the link is somewhat marginal. The second example causes your IP datagrams to be sent in UI frames (unproto or beacon packets). This is the mode of choice on reliable links where very few packets are lost. It reduces overhead so packets are transferred more rapidly.
3.5. Tracing and Monitoring
NET.EXE has the most comprehensive and informative tracing features I have seen in any software package for packet radio. The trace function understand AX.25, IP, TCP, and NET/ROM.
Tracing is enabled for each interface individually. You have the choice of tracing incoming packets, outgoing packets, or both. The format for the trace command is:
trace <interface> TIO
where <interface> is the name of the interface to be traced, T is the trace mode, I is for incoming packets, and O is for outgoing packets. T, I, and O are digits. The following table gives the values for T and their meanings:
0 Trace headers only. Do not display the data.
1 Trace headers and data. Display the data as ASCII, 64 characters to a line.
2 Trace headers and data. Display the entire packet as Hex and ASCII with 16 bytes displayed per line.
The values for I and O are either 1 or 0 depending on whether or not you want the respective incoming or outgoing packets traced or not. Here are some examples:
trace ax0 010
trace ax1 111
trace ax0 201
In the first example incoming packets on interface ax0 will be traced. Only the headers will be displayed. The second example show both incoming and outgoing packets on ax1 being traced. Data in the packets will be displayed as 64 ASCII characters on a line. The last example will display a hex dump of all packets being transmitted on ax0.
I recommend using trace liberally. You will learn a lot about packet radio when you can see what is being sent and to whom. The trace display separates the different headers at the different layers. Trace will display the link, network, and transport layer headers separately so you can see their relationship.
3.6. Running NET and BM Concurrently
In order to get the greatest use out of NET it is important to have it running all the time. The problem with that is that DOS is not a multitasking operating system. It is very frustrating to have to start and stop NET every time you want to do something else. There are solutions: DoubleDos and DesqView.
The DoubleDos and DesqView packages from SoftLogic Solutions and Microsoft, respectively, solve this problem. They permit you to split your memory into two partitions (or more, for DesqView) and allow each program to operate as if it had its own PC. Phil Karn wrote NET with these "multitaskers" in mind and even included the necessary code in NET so that it can effectively reside with other programs without performance penalties to either NET or the other programs. This will also allow you to send and receive mail with BM while NET is still running. That way you will not have to exit from NET every time you want to prepare a mail message or read mail that has arrived.
The first step in using NET with DoubleDOS is to install DoubleDOS according to the instructions. Part of installing DoubleDOS is to modify the file /DDCONFIG.SYS for your environment. Many things can be changed in DDCONFIG.SYS but two are important to NET: size and program to load in the bottom partition. When you edit DDCONFIG.SYS you will find a field named 'bottom size' and a field named 'bottom program.' If you want NET to be started automatically when you start DoubleDOS enter the following in DDCONFIG.SYS:
bottom program = /NET.EXE
DoubleDOS will normally split the available memory in half. This is not the best solution because we know how much memory NET needs and we can then make sure that all of the rest of the available memory is available for the other partition. NET itself needs about 150 Kb of memory. In addition, NET needs COMMAND.COM also loaded in its partition. For this reason you will probably want to allocate about 175 Kb to the bottom partition where NET will run.
Let us assume that you want to have both DoubleDOS and NET start when your system boots (just what you want after a power hit). Add the following entry to your AUTOEXEC.BAT file:
/doubledos
That will cause DoubleDOS to start and DoubleDOS will automatically start NET.
3.7. Installation on a Commodore Amiga
< not written yet >
3.8. Installation on an Apple Macintosh
< not written yet >
3.9. Installation under Unix
< not written yet >
4. Operational Reference
4.1. The NET.EXE Program
The executable file "net.exe" provides both client and server Internet facilities. It implements the various ARPA protocols as both a host and gateway (i.e., it acts as an end-user node as well as an IP packet switch for transit traffic). The keyboard and display is used by the local operator to control both host and gateway level functions, for which a number of commands are provided.
4.1.1. Startup
When net.exe is executed without arguments, it attempts to open the file "autoexec.net" in the root directory of the current drive. If it exists, it is read and executed as though its contents were typed on the console as commands. This feature is useful for setting the local IP address and host name, initializing the IP routing table, and starting the various Internet services. If net.exe is invoked with an argument, it is taken to be the name of an alternate startup file; it is read instead of autoexec.net.
4.1.2. Console mode
The console may be in one of two modes: command mode and converse mode. In command mode, the prompt "net>" is displayed and any of the commands described in the next section may be entered. In converse mode, keyboard input is processed according to the "current session", which may be either a Telnet, FTP or AX.25 connection. In a telnet or AX.25 session, keyboard input is sent to the remote system and any output from the remote system is displayed on the console. In an FTP session, keyboard input is first examined to see if it is a known local command; if so it is executed locally. If not, it is "passed through" to the remote FTP server. (See the section titled "FTP Subcommands").
The keyboard also has "cooked" and "raw" states. In cooked state, input is line-at-a-time; the user may use the line editing characters ^U, ^R and backspace to erase the line, redisplay the line and erase the last character, respectively. Hitting either return or line feed passes the complete line up to the application. In raw mode, each character is immediately passed to the application as it is typed. The keyboard is always in cooked state in command mode. It is also cooked in converse mode on an AX25 or FTP session. In a Telnet session it depends on whether the remote end has issued (and the local end has accepted) the Telnet "WILL ECHO" option. (See the "echo" command).
On the IBM-PC, the user may escape back to command mode by hitting the F10 key. On other systems, the user must enter the "escape" character, which is by default control-] (hex 1d, ASCII GS). (Note that this is distinct from the ASCII character of the same name). The escape character can be changed (see the "escape" command).
4.1.3. Commands
This section describes each of the commands recognized while in command mode. Note that certain FTP subcommands, e.g., put, get, dir, etc, are recognized only in converse mode with the appropriate FTP session; they are not recognized while in command mode. The notation "<hostid>" denotes a host or gateway, which may be specified in one of two ways: as a symbolic name listed in the file "/hosts.net", or as a numeric IP address in dotted decimal notation enclosed by brackets, e.g., [44.0.0.1]. When domain server support is added, ARPA-style domain names (e.g., ka9q.ampr) will also be accepted if a domain server is available on the network to resolve them into IP addresses.
4.1.3.1. <cr>
Entering a carriage return (empty line) while in command mode puts you in converse mode with the current session. If there is no current session, net remains in command mode.
4.1.3.2. !
An alias for the "shell" command.
4.1.3.3. #
Commands starting with the hash mark (#) are ignored. This is mainly useful for comments in the autoexec.net file.
4.1.3.4. arp
Displays the Address Resolution Protocol table that maps IP addresses to their subnet (link) addresses on subnetworks capable of broadcasting. For each IP address entry the subnet type (e.g., Ethernet, AX.25), subnet address and time to expiration is shown. If the link address is currently unknown, the number of IP datagrams awaiting resolution is also shown.
Configure and attach a hardware interface to the system.
a. <hw type> represents the kind of I/O device that is being attached. The following types are supported:
3c500 3Com 3C500 or 3C501 Ethernet interface
asy Standard PC asynchronous interface using the National 8250
hapn Hamilton Amateur Packet Network adapter board (Intel 8273)
eagle Eagle Computer card (Zilog 8530)
pc100 PACCOMM PC-100 (Zilog 8530)
These last two interfaces are still under development; driver code included in this package may or may not work.
B. <I/O address> is the base address of the control registers for the device.
C. <vector> is the interrupt vector number. Both the address and the vector must be in hexadecimal. (You may put "0x" in front of these two values if you wish, but note that they will be interpreted in hex even if you don't use it).
D. <mode> controls how IP datagrams are to be encapsulated in the device's link level protocol; i.e., it selects among several link protocols that may be available. The choices here depend on the interface; at present, the 3c500 interface only supports mode "arpa", which uses standard ARPA-style encapsulation. (In the future, "802" may mean "use 802.3-style encapsulation"). Two modes for the "asy" device are currently supported:
slip Encapsulates IP datagrams directly in SLIP frames without a link header. This is for operation on point-to-point lines and is compatible with 4.2BSD UNIX SLIP).
ax25 Similar to slip, except that an AX.25 header and a KISS TNC control header are added to the front of the datagram before SLIP encoding. Either UI (connectionless) or I (connection-oriented) AX.25 frames can be used; see the "mode" command for details.
The Address Resolution Protocol (ARP) maps IP to Ethernet addresses on Ethernet controllers and to AX.25 addresses on "asy" lines operating in "ax25" mode.
E. <label> gives the name by which the interface will be known to the various commands, such as "connect", "route" and "trace".
F. For asynchronous ports, <bufsize> specifies the size of the ring buffer in bytes to be statically allocated to the receiver; incoming bursts larger than this may (but not necessarily) cause data to be lost. For Ethernet, <bufsize> specifies how many PACKETS may be queued on the receive queue at one time; if this limit is exceeded, further received packets will be discarded. This is useful to prevent the system from running out of memory should another node suddenly develop a case of diarrhea.
G. <mtu> is the Maximum Transmission Unit size, in bytes. Datagrams larger than this limit will be fragmented at the IP layer into smaller pieces. For AX.25 UI frames, this limits the size of the information field. For AX.25 I frames, however, the ax25 paclen parameter is also relevant. If the datagram or fragment is still larger than paclen, it is also fragmented at the AX.25 level (as opposed to the IP level) before transmission. (See the "ax25 paclen" command for further information).
H. <speed> is needed only for an "asy" line; the controller will be initialized to the given speed.
Examples:
# Attach a 3Com Ethernet controller using the standard 3Com address and
# vector (i.e., as it comes out of the box) to use ARPA-standard encapsulation.
# The receive queue is limited to 5 packets, and outgoing packets larger
# than 1500 bytes will be fragmented
attach 3c500 0x300 3 arpa ec0 5 1500
# Attach the PC asynch card normally known as "com1" (the first controller)
# to operate in point-to-point slip mode at 9600 baud, calling it "sl0".
# A 1024 byte receiver ring buffer is allocated. Outgoing packets larger
# than 256 bytes are fragmented.
attach asy 0x3f8 4 slip sl0 1024 256 9600
# Attach the secondary PC asynch card ("com2") to operate in AX.25 mode
# with an MTU of 576 bytes at 9600 baud with a KISS TNC, calling it "ax0".
# By default, IP datagrams are sent in UI frames
attach asy 0x2f8 3 ax25 ax0 1024 576 9600
(Note that you cannot use the second asynch controller ("com2") and a 3Com Ethernet card with standard addressing at the same time because they both use interrupt vector 3).
ax25 digipeat [on|off] Controls whether AX.25 packets addressed to this station as a digipeater will be repeated.
ax25 maxframe [<val]>] Establishes the maximum number of frames that will be allowed to remain unacknowledged at one time on new AX.25 connections. This number cannot be greater than 7.
ax25 mycall [<call>] Display or set the local AX.25 address. The standard format is used, e.g., KA9Q-0 or WB6RQN-5. This command must be given before any attach command using AX.25 mode are given.
ax25 paclen [<val>] Limits the size of I-fields on new AX.25 connections. Note that if IP datagrams or fragments larger than this are transmitted, they will be transparently fragmented at the AX.25 level, sent as a series of I frames, and reassembled back into a complete IP datagram or fragment at the other end of the link. This parameter should be less than the MTU of the associated interface.
ax25 reset <axcb> Deletes the AX.25 connection control block at the specified address.
ax25 retry [<val>] Limits the number of successive unsuccessful re-transmission attempts on new AX.25 connections. If this limit is exceeded, link re-establishment is attempted. If this fails "retry" times, then the connection is abandoned and all queued data is deleted.
ax25 status [<axcb>] Without an argument, displays a one-line summary of each AX.25 control block. If the address of a particular control block is specified, the contents of that control block are dumped in more detail. Note that the send queue units are frames, while the receive queue units are bytes.
ax25 t1 [<val>] ax25 t2 [<val>] ax25 t3 [<val>] Display or set the AX.25 timers to be used for new connections. T1 is the retransmission timer, T2 is the acknowledgement delay timer and T3 is the idle "keep alive" timer. Values are in seconds.
ax25 window [<val>] Sets the number of bytes that can be pending on an AX.25 receive queue beyond which I frames will be answered with RNR (Receiver Not Ready) responses. This presently applies only to suspended interactive AX.25 sessions, since incoming IP datagrams are always processed immediately and not allowed to remain on the receive queue.
cd [<dirname>] Change the current working directory, and display the new setting. Without an argument, cd simply displays the current directory without change. The "pwd" command is an alias for "cd"
close [<session #>] On an AX.25 session, this command initiates a disconnect. On a FTP or Telnet session, this command sends a FIN (i.e., initiates a close) on the session's TCP connection. This is an alternative to asking the remote server to initiate a close ("QUIT" to FTP, or the logout command appropriate for the remote system in the case of Telnet). When either FTP or Telnet sees the incoming half of a TCP connection close, it automatically responds by closing the outgoing half of the connection. Close is more graceful than the "reset" command, in that it is less likely to leave the remote TCP in a "half-open" state.
connect <interface> <callsign> [<digipeater> ... ] Initiates a "vanilla" AX.25 session to the specified call sign using the specified interface. Up to 7 optional digipeaters may be given; note that the word "via" is NOT needed. Data sent on this session goes out in conventional AX.25 packets with no upper layer protocol. The de-facto presentation standard format is used, in that each packet holds one line of text, terminated by a carriage return. A single AX.25 connection may be used for both terminal-to-terminal and IP traffic, with the two types of data being automatically separated by their AX.25 Level 3 Protocol IDs.
dir [<dirname>] List the contents of the specified directory on the console. If no argument is given, the current directory is listed.
disconnect [<session #>] An alias for the "close" command (for the benefit of AX.25 users).
echo [accept|refuse] Displays or changes the flag controlling client Telnet's response to a remote WILL ECHO offer.
The Telnet presentation protocol specifies that in the absence of a negotiated agreement to the contrary, neither end echoes data received from the other. In this mode, a Telnet client session echoes keyboard input locally and nothing is actually sent until a carriage return is typed. Local line editing is also performed: backspace deletes the last character typed, while control-U deletes the entire line.
When communicating from keyboard to keyboard the standard local echo mode is used, so the setting of this parameter has no effect. However, many timesharing systems (e.g., UNIX) prefer to do their own echoing of typed input. (This makes screen editors work right, among other things). Such systems send a Telnet WILL ECHO offer immediately upon receiving an incoming Telnet connection request. If "echo accept" is in effect, a client Telnet session will automatically return a DO ECHO response. In this mode, local echoing and editing is turned off and each key stroke is sent immediately (subject to the Nagle tinygram algorithm in TCP). While this mode is just fine across an Ethernet, it is clearly inefficient and painful across slow paths like packet radio channels. Specifying "echo refuse" causes an incoming WILL ECHO offer to be answered with a DONT ECHO; the client Telnet session remains in the local echo mode. Sessions already in the remote echo mode are unaffected. (Note: Berkeley Unix has a bug in that it will still echo input even after the client has refused the WILL ECHO offer. To get around this problem, enter the "stty -echo" command to the shell once you have logged in.)
4.1.3.6. eol [unix|standard]
Displays or changes Telnet's end-of-line behavior when in remote echo mode. In standard mode, each key is sent as-is. In unix mode, carriage returns are translated to line feeds. This command is not necessary with all UNIX systems; use it only when you find that a particular system responds to line feeds but not carriage returns. Only Sun UNIX release 3.2 seems to exhibit this behavior; later releases are fixed.
4.1.3.7. escape <char>
Without arguments, displays the current command-mode escape character in hex. If given an argument, the first character becomes the new escape character. (This command is not provided on the IBM-PC; on the PC, the escape char is always F10.)
Exit the "net" program and return to MS-DOS (or CP/M).
4.1.3.10. ftp <hostid>
Open an FTP control channel to the specified remote host and enter converse mode on the new session. Responses from the remote server are displayed directly on the screen.
4.1.3.11. help
Display a brief summary of top-level commands.
4.1.3.12. hostname [<name>]
Displays or sets the local host's name (an ASCII string such as "ka9q-pc", NOT an IP address). Currently this is used only in the greeting messages from the SMTP (mail) and FTP (file transfer) servers.
4.1.3.13. log [stop | <file>]
Without arguments, indicates whether server sessions are being logged. If "stop" is given as the argument, logging is terminated (the servers themselves are unaffected). If a file name is given as an argument, server session log entries will be appended to it.
4.1.3.14. ip address [<hostid>]
Displays or sets the local IP address.
4.1.3.15. ip status
Displays Internet Protocol (IP) statistics, such as total packet counts and error counters of various types. Also displays statistics about the Internet Control Message Protocol (ICMP), including the number of ICMP messages of each type sent or received.
4.1.3.16. ip ttl [<val>]
Displays or sets the default time-to-live value placed in each outgoing IP datagram. This limits the number of switch hops the datagram will be allowed to take. The idea is to bound the lifetime of the packet should it become caught in a routing loop, so make the value somewhat larger than the diameter of the network.
4.1.3.17. memstat
Displays the internal free memory list in the storage allocator.
4.1.3.18. mode <interface> [vc|datagram]
Controls the default transmission mode on the specified AX.25 interface. In "datagram" mode, IP packets are encapsulated in AX.25 UI frames and transmitted without any other link level mechanisms, such as connections or acknowledgements.
In "vc" (virtual circuit) mode, IP packets are encapsulated in AX.25 I frames and are acknowledged at the link level according to the AX.25 protocol. Link level connections are opened if necessary. With the proper setting of the AX.25 T2 (acknowledgement delay) timer, AX.25 acknowledgements can be piggybacked on I frames carrying other IP datagrams (e.g., TCP level acknowledgements), thereby eliminating the extra overhead ordinarily incurred by link level acknowledgments.
In both modes, ARP is used to map IP to AX.25 addresses. The defaults can be overridden with the type-of-service (TOS) bits in the IP header. Turning on the "reliability" bit causes I frames to be used, while turning on the "low delay" bit uses UI frames. (The effect of turning on both bits is undefined and subject to change).
In both modes, IP-level fragmentation is done if the datagram is larger than the interface MTU. In virtual circuit mode, however, the resulting datagram (or fragments) is further fragmented at the AX.25 layer if it (or they) are still larger than the AX.25 "paclen" parameter. In AX.25 fragmentation, datagrams are broken into several I frames and reassembled at the receiving end before being passed to IP. This is preferable to IP fragmentation whenever possible because of decreased overhead (the IP header isn't repeated in each fragment) and increased robustness (a lost fragment is immediately retransmitted by the link layer).
4.1.3.19. param <interface> [param ...]
Param invokes a device-specific control routine. On a KISS TNC interface, this sends control packets to the TNC. Data bytes are treated as decimal. For example, "param ax0 1 255" will set the keyup timer (type field = 1) on the KISS TNC configured as ax0 to 2.55 seconds (255 x .01 sec). On a SLIP interface, the param command allows the baud rate to be read (without arguments) or set. The implementation of this command for the various interface drivers is incomplete and subject to change.
4.1.3.20. pwd [<dirname>]
An alias for the cd command.
4.1.3.21. record [<filename>|off]
Opens <filename> and appends to it all data received on the current session. Data sent on the current session is also written into the file except for Telnet sessions in remote echo mode. The command "record off" stops recording and closes the file. This command is not supported for FTP sessions.
4.1.3.22. reset [<session>]
If an argument is given, force a local reset (deletion) of the AX.25 (AXCB) or TCP Control Block (TCB) belonging to the specified session. The argument is first checked for validity. If no argument is given, the current session, if any, is used. This command should be used with caution since it does not inform the remote end that the connection no longer exists. (In TCP a reset (RST) message will be automatically generated should the remote TCP send anything after a local reset has been done. In AX.25 the DM message performs a similar role. Both are used to get rid of a lingering half-open connection after a remote system has crashed.)
With no arguments, "route" displays the IP routing table. "route add" adds an entry to the routing table, while "route drop" deletes an existing entry. "route add" requires at least two more arguments, the host id of the target destination and the local name of the interface to which its packets should be sent. If the destination is not local, the gateway's host id should also be specified. (If the interface is a point-to-point link, then <gateway hostid> may be omitted even if the target is non-local because this field is only used to determine the gateway's link level address, if any. If the destination is directly reachable, <gateway hostid> is also unnecessary since the destination address is used to determine the interface link address).
The optional "/bits" suffix to the destination host id specifies how many leading bits in the host id are to be considered significant in the routing comparisons. If not specified, 32 bits (i.e., full significance) is assumed. With this option, a single routing table entry may refer to many hosts all sharing a common bit string prefix in their IP addresses. For example, ARPA Class A, B and C networks would use suffixes of /8, /16 and /24 respectively; the command
route add [44]/8 sl0 [44.64.0.2]
causes any IP addresses beginning with "44" in the first 8 bits to be routed to [44.64.0.2]; the remaining 24 bits are "don't-cares".
When an IP address to be routed matches more than one entry in the routing table, the entry with largest "bits" parameter (i.e., the "best" match) is used. This allows individual hosts or blocks of hosts to be exceptions to a more general rule for a larger block of hosts.
The special destination "default" is used to route datagrams to addresses not in the routing table; it is equivalent to specifying a /bits suffix of /0 to any destination hostid. Care must be taken with default entries since two nodes with default entries pointing at each other will route packets to unknown addresses back and forth in a loop until their time-to-live (TTL) fields expire. (Routing loops for specific addresses can also be created, but this is less likely to occur accidentally).
"route drop" deletes an entry from the table. If a packet arrives for the deleted address and a default route is in effect, it will be used.
Here are some examples of using the route command:
# Route datagrams to IP address 44.0.0.3 to SLIP line #0.
# No gateway is needed because SLIP is point-to point.
route add [44.0.0.3] sl0
# Route all default traffic to the gateway on the local Ethernet
# with IP address [44.0.0.1]
route add default ec0 [44.0.0.1]
# The local Ethernet has an ARPA Class-C address assignment;
# route all IP addresses beginning with 192.4.8 to it
route add [192.4.8]/24 ec0
# The station with IP address [44.0.0.10] is on the local AX.25 channel
route add [44.0.0.10] ax0
4.1.3.24. session [<session #>]
Without arguments, displays the list of current sessions, including session number, remote TCP or AX.25 address and the address of the TCP or AX.25 control block. An asterisk (*) is shown next to the "current" session; entering <cr> at this point will put you in converse mode with that session. Entering a session number as an argument to the session command will put you in converse mode with that session. If the telnet server is enabled, the user is notified of an incoming request and a session number is automatically assigned. The user may then select the session normally to converse with the remote user as though the session had been locally initiated.
4.1.3.25. shell
Suspends "net" and executes a sub shell ("command processor" under MS-DOS). When the sub shell exits, net resumes (under MS-DOS, enter the "exit" command). Note that background activity (FTP servers, etc) is also suspended while the subshell executes.
4.1.3.26. smtp gateway [<hostid>]
Displays or sets the host to be used as a "smart" mail relay. Any mail sent to a hostid not in the host table will instead be sent to the gateway for forwarding.
4.1.3.27. smtp kick
Run through the outgoing mail queue and attempt to deliver any pending mail. This command is periodically invoked by a timer whenever net is running; this command allows the user to "kick" the mail system manually.
4.1.3.28. smtp maxclients [<val>]
Displays or sets the maximum number of simultaneous outgoing SMTP sessions that will be allowed. The default is 10; reduce it if network congestion is a problem.
4.1.3.29. smtp timer [<val>]
Displays or sets the interval, in seconds, between scans of the outbound mail queue. For example, "smtp timer 600" will cause the system to check for outgoing mail every 10 minutes and attempt to deliver anything it finds, subject of course to the "maxclients" limit. Setting a value of zero disables queue scanning altogether, note that this is the default! This value is recommended for stand alone IP gateways that never handle mail, since it saves wear and tear on the floppy disk drive.
4.1.3.30. smtp trace [<val>]
Displays or sets the trace flag in the SMTP client, allowing you to watch SMTP's conversations as it delivers mail. Zero (the default) disables tracing.
4.1.3.31. start ftp|smtp|telnet|discard|echo
Starts the specified Internet server, allowing remote connection requests.
4.1.3.32. stop ftp|smtp|telnet|discard|echo
Stops the specified Internet server, rejecting any further remote connect requests. Existing connections are allow to complete normally.
4.1.3.33. tcp irtt [<val>]
Display or set the intial round trip time estimate, in seconds, to be used for new TCP connections until they can measure and adapt to the actual value. The default is 5 seconds. Increasing this when operating over slow channels will avoid the flurry of retransmissions that would otherwise occur as the smoothed estimate settles down at the correct value. Note that this command should be given before servers are started in order for it to have effect on incoming connections.
4.1.3.34. tcp kick <tcb.addr>
If there is data on the send queue of the specified tcb, this command forces an immediate retransmission.
4.1.3.35. tcp mss [<size>]
Display or set the TCP Maximum Segment Size in bytes that will be sent on all outgoing TCP connect request (SYN segments). This tells the remote end the size of the largest segment (packet) it may send. Changing MSS affects only future connections; existing connections are unaffected.
4.1.3.36. tcp reset <tcbaddr>
Deletes the TCP control block at the specified address.
4.1.3.37. tcp rtt <tcbaddr> <rttval>
Replaces the automatically computed round trip time in the specified tcb with the rttval in milliseconds. This command is useful to speed up recovery from a series of lost packets since it provides a manual bypass around the normal backoff retransmission timing mechanisms.
4.1.3.38. tcp status [<tcb.addr>]
Without arguments, displays several TCP-level statistics, plus a summary of all existing TCP connections, including TCB address, send and receive queue sizes, local and remote sockets, and connection state. If <tcbddr> is specified, a more detailed dump of the specified TCB is generated, including send and receive sequence numbers and timer information.
4.1.3.39. tcp window [<val>]
Displays or sets the default receive window size in bytes to be used by TCP when creating new connections. Existing connections are unaffected.
4.1.3.40. telnet <hostid>
Creates a Telnet session to the specified host and enters converse mode.
4.1.3.41. trace [<interface> [<flags>]]
Controls packet tracing by the interface drivers. Specific bits enable tracing of the various interfaces and the amount of information produced. Tracing is controlled on a per-interface basis; without arguments, trace gives a list of all defined interfaces and their tracing status. Output can be limited to a single interface by specifying it, and the control flags can be changed by specifying them as well. The flags are given as a hexadecimal number which is interpreted as follows:
TIO
||| Enable tracing of output packets if 1, disable if 0
|| Enable tracing of input packets if 1, disable if 0
| Controls type of tracing:
0 - Protocol headers are decoded, but data is not displayed
1 - Protocol headers are decoded, and data (but not the headers themselves) are displayed as ASCII characters, 64 characters/line. Unprintable characters are displayed as periods.
2 - Protocol headers are decoded, and the entire packet (headers AND data) is also displayed in hexadecimal and ASCII, 16 characters per line.
4.1.3.42. udp status
Displays the status of all UDP receive queues.
4.1.3.43. upload [<filename>]
Opens <filename> and sends it on the current session as though it were typed on the terminal. Valid only on AX.25 and Telnet sessions.
4.1.3.44. ?
Same as the "help" command.
4.1.4. FTP Subcommands
When in converse mode with an FTP server, everything typed on the console is first examined to see if it is a locally-known command. If not, the line is passed intact to the remote server on the control channel. If it is one of the following commands, however, it is executed locally. (Note that this generally involves other commands being sent to the remote server on the control channel.) When actively transferring a file, the only acceptable command is "abort"; all other commands will result in an error message.
4.1.4.1. abort
Aborts a get, put or dir operation in progress. When receiving a file, abort simply resets the data connection; the next incoming data packet will generate a TCP RST (reset) in response which will clear the remote server. When sending a file, abort sends a premature end-of-file. Note that in both cases abort will leave a partial copy of the file on the destination machine, which must be removed manually if it is unwanted. Abort is valid only when a transfer is in progress.
4.1.4.2. dir [<file>|<directory> [<local file>]]
Without arguments, "dir" requests that a full directory listing of the remote server's current directory be sent to the terminal. If one argument is given, this is passed along in the LIST command; this can be a specific file or subdirectory that is meaningful to the remote file system. If two arguments are given, the second is taken as the local file into which the directory listing should be put (instead of being sent to the console). The PORT command is used before the LIST command is sent.
4.1.4.3. get <remote file> [<local file>]
Asks the remote server to send the file specified in the first argument. The second argument, if given, will be the name of the file on the local machine; otherwise it will have the same name as on the remote machine. The PORT and RETR commands are sent on the control channel.
4.1.4.4. ls [<file>|<directory> [<local file>]]
ls is identical to the "dir" command except that the "NLST" command is sent to the server instead of the "LIST" command. This results in an abbreviated directory listing, i.e., one showing only the file names themselves without any other information.
4.1.4.5. mkdir <remote directory>
Creates a directory on the remote machine.
4.1.4.6. put <local file> [<remote file>]
Asks the remote server to accept data, creating the file named in the first argument. The second argument, if given, will be the name of the file on the remote machine; otherwise it will have the same name as on the local machine. The PORT and STOR commands are sent on the control channel.
4.1.4.7. rmdir <remote directory>
Deletes a directory on the remote machine.
4.1.4.8. type [a | i | l <bytesize>]
Tells both the local client and remote server the type of file that is to be transferred. The default is 'a', which means ASCII (i.e., a text file). Type 'i' means "image", i.e., binary. In ASCII mode, files are sent as varying length lines of text in ASCII separated by cr/lf sequences; in IMAGE mode, files are sent exactly as they appear in the file system. ASCII mode should be used whenever transferring text between dissimilar systems (e.g., UNIX and MS-DOS) because of their different end-of-line and/or end-of-file conventions. When exchanging text files between machines of the same type, either mode will work but IMAGE mode may be somewhat faster. Naturally, when exchanging raw binary files (executables, compressed archives, etc) IMAGE mode must be used. Type 'l' (logical byte size) is used when exchanging binary files with remote servers having oddball word sizes (e.g., DECSYSTEM-10s and 20s). Locally it works exactly like IMAGE, except that it notifies the remote system how large the byte size is. <bytesize> is typically 8. The type command sets the local transfer mode and generates the TYPE command on the control channel.
4.1.5. FTP server configuration
Since MS-DOS was designed as a single-user operating system, it provides no access control; all files can be read, written or deleted by the local user. It is usually undesirable to give such open access to a system to remote network users. The FTP server therefore provides its own access control mechanism.
The file "/ftpusers" is used to control remote FTP access. The default is NO access; if this file does not exist, the FTP server will be unusable. A remote user must first "log in" to the system with the USER and PASS commands, giving a valid name and password listed in /ftpusers, before he or she can transfer files.
Each entry in /ftpusers consists of a single line of the form
username password /path permissions
There must be exactly four fields, and there must be exactly one space between each field. Comments may be added after the last field. Comment lines are begun with "#" in column one.
a. "username" is the user's login name.
b. "password" is the required password. Note that this is in plaintext; therefore it is not a good idea to give general read permission to the root directory. A password of "*" (a single asterisk) means that any password is acceptable.
c. "/path" is the allowable prefix on accessible files. Before any file or directory operation, the current directory and the userspecified file name are joined to form an absolute path name in "canonical" form (i.e., a full path name starting at the root, with "./" and "../" references, as well as redundant /'s, recognized and removed). The result MUST begin with the allowable path prefix; if not, the operation is denied. NB! Under MS-DOS, this field must use backslashes ("\"), NOT forward slashes ("/"). This field must always begin with a "/", i.e., at the root directory.
d. "permissions" is a decimal number granting permission for read, create and write operations. If the low order bit (0x1) is set, the user is allowed to read a file subject to the path name prefix restriction. If the next bit (0x2) is set, the user is allowed to create a new file if it does not overwrite an existing file. If the third bit (0x4) is set, the user is allowed to write a file even if it overwrites an existing file, and in addition he may delete files. Again, all operations are allowed subject to the path name prefix restrictions. Permissions may be combined by adding bits, for example, 0x3 (= 0x2 + 0x1) means that the user is given read and create permission, but not overwrite/delete permission.
For example, suppose /ftpusers on machine "pc.ka9q.ampr" contains the line
friendly test /testdir 7
A session using this account would look like this:
net> ftp pc.ka9q.ampr
SYN Sent
Established
250 pc.ka9q.ampr FTP version 871225.5 ready at Wed Jan 20 16:27:18 1988
user friendly
331 Enter PASS command
pass test
230 Logged in
The user now has read, write, overwrite and delete privileges for any file under /testdir; he may not access any other files.
Here are some more sample entries in /ftpusers:
karn foobar / 7 # User "karn" with password "foobar" may read, write, overwrite and delete any file on the system.
guest bletch /g/bogus 3 # User "guest" with password "bletch" may read any file under /g/bogus and its subdirectories, and may create a new file as long as it does not overwrite an existing file. He may NOT delete any files.
anonymous * /public 1 # User "anonymous" (any password) may read files under /public and its subdirectories; he may not create, overwrite or delete any files.
I recommend this last entry as a standard convention for keeping a repository of downloadable files; in particular, the username "anonymous" is an established ARPA convention.
4.2. The BM.EXE Mail User Interface Program
Many thanks to Gerard PA0GRI who is primarily responsible for the addition of features to version 2, and to Dave Trulli NN2Z who is responsible for the changes and additions making up version 3.
4.2.1. Configuring the SMTP Environment
As supplied, the SMTP server and client make assumptions about the disk space available to them. In particular, the file handling portion of the client and server will need to be modified heavily if used on any operating system other than PC-Dos or MS-Dos. Sorry.
To achieve minimum functionality, you should create directories /spool/mail and /spool/mqueue on the default disk used when running net.exe... the mail directory is used by the server for storing incoming mail, the mqueue directory is where the client looks to find outbound messages that need to be delivered.
There is one command in net.exe that relates to the SMTP client operation. It is 'smtp'. Issuing this command will cause the client to attempt to deliver mail immediately. Normally, the client will fire up 15 mins after the end of the previous invocation to try and process outbound mail. The smtp command is primarily a debugging tool, and should be used as such.
4.2.1.1. File Formats
Incoming mail for users on the current host gets placed in 'mailbox' files in the /spool/mail directory. The name of the file is based on the user name given by the sending SMTP agent. These are simple text files, with new messages appended to the end. If a mailbox file does not exist, the server will create it automagically. Messages in the files are in RFC822 format, with new messages appended to the end. The first line of each message will always start with the token 'Received:', quotes not included. This line is added by the server to indicate the date and time the message was received, and the host it was received from.
Outgoing mail messages consist of two files each in the /spool/mqueue directory. The names of the two files will be of the form <integer>.WRK and <integer>.TXT, where integer is the sequence number of the message relative to this machine. The file sequence.seq in the mqueue directory contains the current sequence number for reference by the mail user interface. The .TXT file contains the data portion of the SMTP transaction, in full RFC822 format. The .WRK file consists of 3 lines, as follows:
o+ the hostname of the destination system
o+ the full sender address, in user@host format.
o+ the full destination address, in user@host format.
The mailer does not yet support multiple recipients; when it does, the .wrk file format will contain extra destination address lines, one for each additional recipient.
4.2.1.2. Bugs and Limitations
The SMTP server does not allow forwarding. In a perfect world, forwarding is a crock. Since we do not live in a perfect world, some specialized forward capability will probably be added eventually... though we'd like to avoid it! Better to just put a bsd4.X system on the air and let Sendmail handle the grody work! :-)
The SMTP client only understands a single destination address in the TO line. This is a legal minimal implementation of the standard, but will eventually change. Note that the format of the .WRK file will change when this does, of necessity.
Error returns from the remote server are not properly handled. The mailer will keep trying to deliver the mail each time the smtp command is issued (or invoked automatically by the timer). There is as yet no mechanism for "bouncing" mail back to the sender when it cannot be sent.
The smtp client (mail sender) code in net.exe now tries to connect to all destination hosts simultaneously. If there is a lot of mail in the outbound queue, this may cause problems. In particular, try using the FILES= parameter in the MS-DOS config.sys file to allow net.exe to have more than the default 8 files open at once.
4.2.1.3. For More Information
The SMTP specification is RFC821. The Format for text messages (including the headers) is in RFC822. RFC819 discusses hostname naming conventions, particularly domain naming.
4.2.2. BM Setup
In order to make use of BM, you must first follow the installation instructions in the file SMTP.DOC to provide minimal SMTP support. Then, you should:
o+ copy the files BM.RC and HOSTS.NET to the root directory of the default drive used when NET.EXE is running.
o+ edit HOSTS.NET to reflect the hosts you will exchange mail with. the format of each line of this file is:
IPddress <tab> hostname <newline>
The IP address should be of the form 0.0.0.0, and the hostname can be any token you wish to use to represent that host. In particular, it does NOT need to be the full legal name of the host.
o+ edit the file /BM.RC to correctly identify your hostname, username, and the IP address of the system you wish to punt mail to when you don't know the correct IP address. The format lines in this file is:
token <space> value <newline>
where the currently defined tokens are 'host' for this system's hostname, 'user' for your username, and 'gate' for the ip address of the nearest 'smart mailer'. More on this below. Additional tokens exist for setting your local timezone, and mailbox directory, and editor to be used in message creation.
4.2.3. Operation
BM is designed to serve as the mail user-interface for users of the KA9Q internetworking software package. The purpose of BM is to provide a full set of electronic mail services to the user. These include sending messages, listing and reading received messages, and so forth.
BM reads mailbox files created by the SMTP server in NET.EXE, which are stored in a directory (usually /spool/mail) that is specified in the config file /bm.rc. Incoming mail is stored by the server in mailbox files, one per username. These mailbox files may also be referred to as "notefiles". The default mailbox to read is specified with the 'user' option in the /bm.rc file. This username is also used on all outgoing messages.
The /bm.rc file also defines a timezone stamp, which in conjunction with the DOS date and time is used to provide the required RFC822 Date: header.
Commands are generally one character long and followed by a space, and parameter if needed:
s Send a message. The user is prompted for a destination address and subject. BM then creates appropriate RFC822 headers in a temporary file, and either invokes the user's favorite editor (specified with the 'edit' parameter in /bm.rc) to enter the message text, or uses a simple/stupid text entry routine if no editor is defined. Note that if you are using an editor, you should start by jumping to the end of the file. RFC822 requires that the headers be first and be separated from the text of a message by at least one blank line.
In this release, Phil KA9Q has modified BM slightly to be more like the Berkeley Unix mail program. When the message entry routine first starts, you will be in the silly text editor. If you want to use your editor on the message, type '~e<ret>'... not obvious to most folks, but very obvious to 4bsd fans... [sigh].
t Transmits an already created file as a message. RFC822 headers are prepended. This is useful if you don't have an editor that will work with the 's' command.
*** NOTE *** RFC822 only allows 7bit data. If you want to send a binary file, use BSQ, or UUENCODE, or something similar to convert it to a text file first! Better yet, use FTP...
r Read all messages in the current notefile.
u Updates you with new messages in the notefile, shows them to you and updates the read marker to the last one read. If no new messages came in, you will be notified.
f Forward a message to someone else. A temporary copy is made of the message specified and that is handed over to the send message routine, which treats it as a file ala the 't' command.
d Delete a message. Parameter is the message number. If the number of the to be deleted message is higher than the last read message an "are you sure" message is printed. 'Y' or 'y' will delete it...
h Displays message headers, a message number, received date, from whom and the subject fields on an single line. An star is put in front of the last read message.
p Sets the printer on or off so messages to the screen also go to the printer. ** This will be implemented in a future release. **
l Lists the file names of messages waiting to be sent that are in the queue directory, usually /spool/mqueue. Primarily useful for debugging.
n Shows the notefiles in the mail directory, the location of which is specified by the 'smtp' parameter in the /bm.rc file. If this command is followed with a parameter, the current notefile will be changed to the specified notefile. If it does not exist you will be notified if you try something with it.
# Substitute # with a number (1..whatever) and it will show you the message in the current active notefile with that number. If the message is the one next to the last read one the * will be moved.
? Prints a short command summary to the screen.
q Quit.
The program's prompt will always show the current notefile name.
4.2.4. Additional Information
BM will prompt you for a To: address. This should be in the form user@host, where user will be the name of the mailbox file on the destination KA9Q system, or the username of the intended recipient on other SMTP-equipped systems. The host field should exactly match a host token in the HOSTS.NET file. If it does not, the SMTP client in NET.EXE will insert the IP address of the nearest "smart mail agent" in the work file instead of the destination IP address (since it is unknown). The rationale behind this is that many SMTP equipped systems include the ability to forward mail that is not addressed to them. If you have a system of this type nearby, you may be able to "punt" mail to them for handling.
Note that if there is such a smart mailer on a system near you, you can replace the simple 'user' field with a full address that the smart mailer can understand, since BM will scan from the right taking everything after the rightmost '@' to be the host token, and will not mangle the address. For example, from my PC clone I can easily mail to:
bellcore!karn@winfree (to get to Phil, KA9Q)
where winfree is my Unix system, which talks to system bellcore via UUCP. BM really doesn't care what you put for an address as long as there is a system within range that it can punt to when it doesn't understand what you mean. Note that this implies you should be extra careful when typing addresses!
Read the SMTP.DOC file for specification of the queue and mailbox files, and limitations of the SMTP client that affect BM's capabilities.
5. Appendices
5.1. Technical Information for Client/Server Developers
This section describes the "guts" of the Internet package for the benefit of programmers who wish to write their own applications, or adapt the code to different hardware environments.
The code as distributed includes both the functions of an IP packet switch and an end-host system, including several servers. The implementation is highly modular, however. For example, if one wants to build a dedicated packet switch without any local applications, the various applications and the TCP and UDP modules may easily be omitted to save space.
The package allows multiple simultaneous applications, each supporting multiple simultaneous users, each using TCP and/or UDP. The only limit is memory space, which is getting quite tight on the 820; the C compiler for the IBM PC seems to generate much more compact code (typically 1/2 as large as for the Z-80) so the PC seems more promising as a large-scale server.
5.1.1. Data Structures
To increase portability, the pseudo-types "int16" and "int32" are used to mean an unsigned 16-bit integer and a signed 32-bit integer, respectively. Ordinarily these types are defined in machdep.h to be "unsigned int" and "long".
The various modules pass data in chained structures called mbufs, with the following format:
struct mbuf {
struct mbuf *next; /* Links mbufs belonging to single packets */
struct mbuf *anext; /* Links packets on queues */
char *data; /* Pointer to start of actual data in buffer */
int16 cnt; /* Length of data in buffer */
};
Although somewhat cumbersome to work with, mbufs make it possible to avoid memory-to-memory copies that limit performance. For example, when user data is transmitted it must first traverse several protocol layers before reaching the transmitter hardware. With mbufs, each layer adds its protocol header by allocating an mbuf and linking it to the head of the mbuf "chain" given it by the higher layer, thus avoiding several copy operations.
A number of primitives operating on mbufs are available in mbuf.c. The user may create, fill, empty and free mbufs himself with the allocbuf and freebuf primitives, or at the cost of a single memory-to-memory copy he he may use the more convenient qdata() and dqdata() primitives.
5.1.2. Timer Services
TCP and IP require timers. A timer package is included, so the user must arrange to call the single entry point "tick" on a regular basis. The constant MSPTICK in timer.h should be defined as the interval between ticks in milliseconds. One second resolution is adequate. Since it can trigger a considerable amount of activity, including upcalls to user level, "tick" should not be called from an interrupt handler. A clock interrupt should set a flag which will then cause "tick" to be called at user level.
5.1.3. Internet Type-of-Service
One of the features of the Internet is the ability to specify precedence (i.e., priority) on a per-datagram basis. There are 8 levels of precedence, with the bottom 6 defined by the DoD as Routine, Priority, Immediate, Flash, Flash Override and CRITICAL. (Two more are available for internal network functions). For amateur use we can use the lower four as Routine, Welfare, Priority and Emergency. Three more bits specify class of service, indicating that especially high reliability, high throughput or low delay is needed for this connection. Constants for this field are defined in internet.h.
5.1.4. The Internet Protocol Implementation
While the user does not ordinarily see this level directly, it is described here for sake of completeness. Readers interested only in the interfaces seen by the applications programmer should skip to the TCP and UDP sections.
The IP implementation consists of three major functions: ipoute, ipend and ipecv.
5.1.5. IP Gateway (Packet Router) Support
The first, ipoute, is the IP packet switch. It takes a single argument, a pointer to the mbuf containing the IP datagram:
void
ipoute(bp,rxbroadcast)
struct mbuf *bp; /* Datagram pointer */
int rxbroadcast; /* Don't forward */
All IP datagrams, coming or going, pass through this function. After option processing, if any, the datagram's destination address is extracted. If it corresponds to the local host, it is "kicked upstairs" to the upper half of IP and thence to the appropriate protocol module. Otherwise, an internal routing table consulted to determine where the datagram should be forwarded. The routing table uses hashing keyed on IP destination addresses, called "targets". If the target address is not found, a special "default" entry, if available, is used. If a default entry is not available either, an ICMP "Destination Unreachable" message containing the offending IP header is returned to the sender.
The "rxbroadcast" flag is used to prevent forwarding of broadcast packets, a practice which might otherwise result in spectacular routing loops. Any subnet interface driver receiving a packet addressed to the broadcast address within that subnet MUST set this flag. All other packets (including locally originated packets) should have "rxbroadcast" set to zero.
ipoute ignores the IP destination address in broadcast packets, passing them up to the appropriate higher level protocol which is also made aware of their broadcast nature. (TCP and ICMP ignore them; only UDP can accept them).
Entries are added to the IP routing table with the rtdd function:
int
rtdd(target,gateway,metric,interface)
int32 target; /* IP address of target */
int32 gateway; /* IP addr of gateway to reach this target */
int metric; /* "cost" metric, for routing decisions */
"target" is the IP address of the destination; it becomes the hash index key for subsequent packet destination address lookups. If target == 0, the default entry is modified. "metric" is simply stored in the table; it is available for routing cost calculations when an automatic routing protocol is written. "interface" is the address of a control structure for the particular device to which the datagram should be sent; it is defined in the section "IP Interfaces".
rtdd returns 0 on success, -1 on failure (e.g., out of memory).
To remove an entry from the routing table, only the target address need be specified to the rtrop call:
int
rtrop(target)
int32 target;
rtrop returns 0 on success, -1 if the target could not be found.
5.1.6. IP Interfaces
Every lower level interface used to transmit IP datagrams must have an "interface" structure, defined as follows:
/* Interface control structure */
struct interface {
struct interface *next; /* Linked list pointer */
char *name; /* Ascii string with interface name */
int16 mtu; /* Maximum transmission unit size */
int (*send)(); /* Routine to call to send datagram */
int (*output)(); /* Routine to call to send raw packet */
int (*recv)(); /* Routine to kick to process input */
int (*stop)(); /* Routine to call before detaching */
int16 dev; /* Subdevice number to pass to send */
int16 flags; /* State of interface */
#define IFCTIVE 0x01
#define IFROADCAST 0x04 /* Interface is capable of broadcasting */
};
Part of the interface structure is for the private use of the device driver. "dev" is used to distinguish between one of several identical devices (e.g., serial links or radio channels) that might share the same send routine.
A pointer to this structure kept in the routing table. Two fields in the interface structure are examined by ipoute: "mtu" and "send". The maximum transmission unit size represents the largest datagram that this device can handle; ipoute will do IP-level fragmentation as required to meet this limit before calling "send", the function to queue datagrams on this interface. "send" is called as follows:
The "interface" and "gateway" arguments are kept in the routing table and passed on each call to the send routine. The interface pointer is passed again because several interfaces might share the same output driver (e.g., several identical physical channels). "gateway" is the IP address of the neighboring IP gateway on the other end of the link; if a link-level address is required, the send routine must map this address either dynamically (e.g., with the Address Resolution Protocol, ARP) or with a static lookup table. If the link is point-to-point, link-level addresses are unnecessary, and the send routine can therefore ignore the gateway address.
The Internet Type-of-Service (TOS) bits are passed to the interface driver as separate arguments. If tradeoffs exist within the subnet between these various classes of service, the driver may use these arguments to control them (e.g., optional use of link level acknowledgments, priority queuing, etc.)
It is expected that the send routine will put a link level header on the front of the packet, add it an internal output queue, start output (if not already active) and return. It must NOT busy-wait for completion (unless it is a very fast device, e.g., Ethernet) since that blocks the entire system.
Any interface that uses ARP must also provide an "output" routine. It is a lower level entry point that allows the caller to specify the fields in the link header. ARP uses it to broadcast a request for a given IP address. It may be the same routine used internally by the driver to send IP datagrams once the link level fields have been determined. It is called as follows:
(*output)(interface,dest,src,type,bp)
struct interface *interface; /* Pointer to interface structure */
char dest[]; /* Link level destination address */
char src[]; /* Link level source address */
int16 type; /* Protocol type field for link level */
struct mbuf *bp; /* Data field (IP datagram) */
5.1.7. IP Host Support
All of the modules described thus far are required in all systems. However, the routines that follow are necessary only if the system is to support higher-level applications. In a stand alone IP gateway (packet switch) without servers or clients, the following modules (IP user level, TCP and UDP) may be omitted to allow additional space for buffering; define the flag GWONLY when compiling iproute.c to avoid referencing the user level half of IP.
The following function is called by iproute() whenever a datagram arrives that is addressed to the local system.
void
ipecv(bp,rxbroadcast)
struct mbuf *bp; /* Datagram */
char rxbroadcast; /* Incoming broadcast */
ipecv reassembles IP datagram fragments, if necessary, and calls the input function of the next layer protocol (e.g., tcpnput, udpnput) with the appropriate arguments, as follows:
struct mbuf *bp; /* Pointer to packet minus IP header */
char protocol; /* IP protocol ID */
int32 source; /* IP address of sender */
int32 dest; /* IP address of destination (i.e,. us) */
char tos; /* IP type-of-service field in datagram */
int16 length; /* Length of datagram minus IP header */
char rxbroadcast; /* Incoming broadcast */
The list of protocols is contained in a switch() statement in the ipecv function. If the protocol is unsupported, an ICMP Protocol Unreachable message is returned to the sender unless the packet came in as a broadcast.
Higher level protocols such as TCP and UDP use the ipend routine to generate IP datagrams. The arguments to ipend correspond directly to fields in the IP header, which is generated and put in front of the user's data before being handed to ipoute:
int16 length; /* Optional length of data portion */
int16 id; /* Optional identification */
char df; /* Don't-fragment flag */
This interface is modeled very closely after the example given on page 32 of RFC-791. Zeros may be passed for id or ttl, and system defaults will be provided. If zero is passed for length, it will be calculated automatically.
5.1.8. The Transmission Control Protocol (TCP)
A TCP connection is uniquely identified by the concatenation of local and remote "sockets". In turn, a socket consists of a host address (a 32-bit integer) and a TCP port (a 16-bit integer), defined by the C structure
struct socket {
long address; /* 32-bit IP address */
short port; /*16-bit TCP port */
};
It is therefore possible to have several simultaneous but distinct connections to the same port on a given machine, as long as the remote sockets are distinct. Port numbers are assigned either through mutual agreement, or more commonly when a "standard" service is involved, as a "well known port" number. For example, to obtain standard remote login service using the TELNET presentation-layer protocol, by convention you initiate a connection to TCP port 23; to send mail using the Simple Mail Transfer Protocol (SMTP) you connect to port 25. ARPA maintains port number lists and periodically publishes them; the latest revision is RFC-960, "Assigned Numbers". They will also assign port numbers to a new application on request if it appears to be of general interest.
TCP connections are best modeled as a pair of one-way paths (one in each direction) rather than single full-duplex paths. A TCP "close" really means "I have no more data to send". Station A may close its path to station B leaving the reverse path from B to A unaffected; B may continue to send data to A indefinitely until it too closes its half of the connection. Even after a user initiates a close, TCP continues to retransmit any unacknowledged data if necessary to ensure that it reaches the other end. This is known as "graceful close" and greatly simplifies certain applications such as FTP.
This package is written as a "module" intended to be compiled and linked with the application(s) so that they can be run as one program on the same machine. This greatly simplifies the user/TCP interface, which becomes just a set of internal subroutine calls on a single machine. The internal TCP state (e.g., the address of the remote station) is easily accessed. Reliability is improved, since any hardware failure that kills TCP will likely take its applications with it anyway. Only IP datagrams flow out of the machine across hardware interfaces (such as asynch RS-232 ports or whatever else is available) so hardware flow control or complicated host/front-end protocols are unnecessary.
The TCP supports five basic operations on a connection: opencp, sendcp, receivecp, closecp and delcp. A sixth, statecp, is provided mainly for debugging. Since this TCP module cannot assume the presence of a sleep/wakeup facility from the underlying operating system, functions that would ordinarily block (e.g., recvcp when no data is available) instead set netrror to the constant EWOULDBLK and immediately return -1. Asynchronous notification of events such as data arrival can be obtained through the upcall facility described earlier.
Each TCP function is summarized in the following section in the form of C declarations and descriptions of each argument.
int netrror;
This global variable stores the specific cause of an error from one of the TCP or UDP functions. All functions returning integers (i.e., all except opencp) return -1 in the event of an error, and netrror should be examined to determine the cause. The possible errors are defined as constants in the header file netuser.h.
void (*rpcall)(); /* Function to call when data arrives */
void (*tpcall)(); /* Function to call when ok to send more data */
void (*spcall)(); /* Function to call when connection state changes */
char tos; /* Internet Type-of-Service */
int *user; /* Pointer for convenience of user */
"lsocket" and "fsocket" are pointers to the local and foreign sockets, respectively.
"mode" may take on three values, all defined in net.user.h. If mode is TCPASSIVE, no packets are sent, but a TCP control block is created that will accept a subsequent active open from another TCP. If a specific foreign socket is passed to a passive open, then connect requests from any other foreign socket will be rejected. If the foreign socket fields are set to zero, or if fsocket is NULLSOCK, then connect requests from any foreign socket will be accepted. If mode is TCPCTIVE, TCP will initiate a connection to a remote socket that must already have been created in the LISTEN state by its client. The foreign socket must be completely specified in an active open. When mode is TCPERVER, opencp behaves as though TCPASSIVE was given except that an internal "clone" flag is set. When a connection request comes in, a fresh copy of the TCP control block is created and the original is left intact. This allows multiple sessions to exist simultaneously; if TCPASSIVE were used instead only the first connect request would be accepted.
"rpcall", "tpcall" and "spcall" provide optional upcall or pseudointerrupt mechanisms useful when running in a non operating system environment. Each of the three arguments, if non-NULL, is taken as the address of a user-supplied function to call when receive data arrives, transmit queue space becomes available, or the connection state changes. The three functions are called with the following arguments:
(*rpcall)(tcb,count); /* count == number of bytes in receive queue */
(*tpcall)(tcb,avail); /* avail == space available in send queue */
(*spcall)(tcb,oldstate,newstate);
Note: whenever a single event invokes more than one upcall the order in which the upcalls are made is not strictly defined. In general, though, the Principle of Least Astonishment is followed. E.g., when entering the ESTABLISHED state, the state change upcall is invoked first, followed by the transmit upcall. When an incoming segment contains both data and FIN, the receive upcall is invoked first, followed by the state change to CLOSEAIT state. In this case, the user may interpret this state change as a "end of file" indicator.
"tos" is the Internet type-of-service field. This parameter is passed along to IP and is included in every datagram. The actual precedence value used is the higher of the two specified in the corresponding pair of opencp calls.
opencp returns a pointer to an internal Transmission Control Block (tcb). This "magic cookie" must be passed back as the first argument to all other TCP calls. In event of error, the NULL pointer (0) is returned and netrror is set to the reason for the error.
The only limit on the number of TCBs that may exist at any time (i.e., the number of simultaneous connections) is the amount of free memory on the machine. Each TCB on a 16-bit processor currently takes up 111 bytes; additional memory is consumed and freed dynamically as needed to buffer send and receive data. Deleting a TCB (see the delcp() call) reclaims its space.
/* Send data on a TCP connection */
int
sendcp(tcb,bp)
struct tcb *tcb; /* TCB pointer */
struct mbuf *bp; /* Pointer to user's data mbufs */
"tcb" is the pointer returned by the opencp() call. "bp" points to the user's mbuf with data to be sent. After being passed to sendcp, the user must no longer access the data buffer. TCP uses positive acknowledgments with retransmission to ensure in-order delivery, but this is largely invisible to the user. Once the remote TCP has acknowledged the data, the buffer will be freed automatically.
TCP does not enforce a limit in the number of bytes that may be queued for transmission, but it is recommended that the application not send any more than the amount passed as "cnt" in the transmitter upcall. The package uses shared, dynamically allocated buffers, and it is entirely possible for a misbehaving user task to run the system out of buffers.
/* Receive data on a TCP connection */
int
recvcp(tcb,bp,cnt)
struct tcb *tcb;
struct mbuf **bp;
int16 cnt;
recvcp() passes back through bp a pointer to an mbuf chain containing any available receive data, up to a maximum of "cnt" bytes. The actual number of bytes received (the lesser of "cnt" and the number pending on the receive queue) is returned. If no data is available, netrror is set to EWOULDBLK and -1 is returned; the rpcall mechanism may be used to determine when data arrives. (Technical note: "rpcall" is called whenever a PUSH or FIN bit is seen in an incoming segment, or if the receive window fills. It is called before an ACK is sent back to the remote TCP, in order to give the user an opportunity to piggyback any data in response.)
When the remote TCP closes its half of the connection and all prior incoming data has been read by the local user, subsequent calls to recvcp return 0 rather than -1 as an "end of transmission" indicator. Note that the local application is notified of a remote close (i.e., end-of-file) by a statechange upcall with the new state being CLOSEAIT; if the local application has closed first, a remote close is indicated by a state-change upcall to either CLOSING or TIMEAIT state. (CLOSING state is used only when the two ends close simultaneously and their FINs cross in the mail).
/* Close a TCP connection */
closecp(tcb)
struct tcb *tcb;
This tells TCP that the local user has no more data to send. However, the remote TCP may continue to send data indefinitely to the local user, until the remote user also does a closecp. An attempt to send data after a closecp is an error.
/* Delete a TCP connection */
delcp(tcb)
struct tcb *tcb;
When the connection has been closed in both connections and all incoming data has been read, this call is made to cause TCP to reclaim the space taken up by the TCP control block. Any incoming data remaining unread is lost.
/* Dump a TCP connection state */
statecp(tcb)
struct tcb *tcb;
This debugging call prints an ASCII-format dump of the TCP connection state on the terminal. You need a copy of the TCP specification (ARPA RFC 793 or MILSTD-1778) to interpret most of the numbers.
5.1.9. The User Datagram Protocol (UDP)
UDP is available for simple applications not needing the services of a reliable protocol like TCP. A minimum of overhead is placed on top of the "raw" IP datagram service, consisting only of port numbers and a checksum covering the UDP header and user data. Four functions are available to the UDP user.
/* Create a UDP control block for lsocket, so that we can queue
* incoming datagrams.
*/
int
opendp(lsocket,rpcall)
struct socket *lsocket;
void (*rpcall)();
opendp creates a queue to accept incoming datagrams (regardless of source) addressed to "lsocket". "rpcall" is an optional upcall mechanism to provide the address of a function to be called as follows whenever a datagram arrives:
(*rpcall)(lsocket,rcvcnt);
struct socket *lsocket; /* Pointer to local socket */
int rcvcnt; /* Count of datagrams pending on queue */
/* Send a UDP datagram */
int
senddp(lsocket,fsocket,tos,ttl,bp,length,id,df)
struct socket *lsocket; /* Source socket */
struct socket *fsocket; /* Destination socket */
char tos; /* Type-of-service for IP */
char ttl; /* Time-to-live for IP */
struct mbuf *bp; /* Data field, if any */
int16 length; /* Length of data field */
int16 id; /* Optional ID field for IP */
char df; /* Don't Fragment flag for IP */
The parameters passed to senddp are simply stuffed in the UDP and IP headers, and the datagram is sent on its way.
/* Accept a waiting datagram, if available. Returns length of datagram */
int
recvdp(lsocket,fsocket,bp)
struct socket *lsocket; /* Local socket to receive on */
struct socket *fsocket; /* Place to stash incoming socket */
struct mbuf **bp; /* Place to stash data packet */
The "lsocket" pointer indicates the socket the user wishes to receive a datagram on (a queue must have been created previously with the opendp routine). "fsocket" is taken as the address of a socket structure to be overwritten with the foreign socket associated with the datagram being read; bp is overwritten with a pointer to the data portion (if any) of the datagram being received.
/* Delete a UDP control block */
int
deldp(lsocket)
struct socket *lsocket;
This function destroys any unread datagrams on a queue, and reclaims the space taken by the queue descriptor.
5.2. The KISS Host to TNC Protocol
5.2.1. The Protocol Specification
5.2.1.1. Introduction
The purpose of the "Raw" (aka "KISS") TNC is to facilitate the use of amateur packet radio controllers (TNCs) with host computers, particularly in the development of experimental protocols and multi-user servers (e.g., "bulletin boards").
Current TNC software was written with human users in mind; unfortunately, commands and responses well suited for human use are ill-adapted for host computer use, and vice versa. This is especially true for multi-user servers such as bulletin boards which must multiplex data from several network connections across the single host/TNC link. In addition, experimentation with new link level protocols is greatly hampered because there may very well be no way at all to generate or receive frames in the desired format without reprogramming the TNC.
The Raw TNC solves these problems by eliminating as much as possible from the TNC software, giving the attached host complete control over and access to the contents of the HDLC frames transmitted and received over the air. The AX.25 protocol is removed entirely from the TNC, as are all command interpreters and the like. The TNC simply converts between synchronous HDLC, spoken on the half duplex radio channel, and a special asynchronous, full duplex frame format spoken on the host/TNC link. Every frame received on the HDLC link is passed intact to the host once it has been translated to the asynchronous format; likewise, asynchronous frames from the host are transmitted on the radio channel once they have been converted to HDLC format.
Of course, this means that the bulk of AX.25 (or another protocol) must now be implemented on the host system. This is acceptable, however, considering the greatly increased flexibility and reduced overall complexity that comes from allowing the protocol to reside on the same machine with the applications to which it is closely coupled.
5.2.1.2. Asynchronous frame format
The "asynchronous packet protocol" spoken between the host and TNC is very simple, since its only function is delimiting frames. Each frame is both preceded and followed by a special FEND (frame end) character, analogous to an HDLC flag. No CRC or checksum is provided.
The reason for both preceding and ending frames with FENDs is to improve performance when there is noise on the asynch line. The FEND at the beginning of a frame serves to "flush out" any accumulated garbage into a separate frame (which will be discarded by the upper layer protocol) instead of prepending it to an otherwise good frame. As with back-to-back FLAGs in HDLC, two FEND characters in a row should not be interpreted as delimiting an empty frame.
5.2.1.2.1. Transparency
Frames are sent in 8-bit binary; if an FEND ever appears in the data, it is translated into the two byte sequence FESC TFEND (frame escape, transposed frame end). Likewise, if the FESC character ever appears in the user data, it is replaced with the two character sequence FESC TFESC (frame escape, transposed frame escape).
As characters arrive at the receiver, they are appended to a buffer containing the current frame. Receiving a FEND marks the end of the current frame. Receipt of a FESC puts the receiver into "escaped mode", which causes the receiver to translate a following TFESC or TFEND back to FESC or FEND, respectively, before adding it to the receive buffer and leaving escaped mode. (Receipt of any character other than TFESC or TFEND while in escaped mode is an error; no action is taken and frame assembly continues. A TFEND or TESC received while not in escaped mode is treated as an ordinary data character.)
This procedure may seem somewhat complicated, but it is easy to implement and recovers quickly from errors. In particular, the FEND character is never sent over the channel except as an actual end-of-frame indication. This ensures that any intact frame (properly delimited by FEND characters) will always be received properly regardless of the starting state of the receiver or corruption of the preceding frame.
The special characters are:
FEND (frame end) 300 (octal)
FESC (frame escape) 333 (octal)
TFEND (transposed frame end) 334 (octal)
TFESC (transposed frame escape) 335 (octal)
(ARPA Internet hackers will recognize this protocol as identical to SLIP, a popular method for sending IP datagrams across ordinary dialup modems).
5.2.1.3. Control of the Raw TNC
Each asynchronous data frame sent to the TNC is converted back into "pure" form and queued for transmission as a separate HDLC frame. Although removing the human interface and the AX.25 protocol from the TNC makes most existing TNC commands unnecessary (i.e., they become host functions), the TNC is still responsible for keying the transmitter's PTT line and deferring to other activity on the radio channel. It is therefore necessary to allow the host to control a few TNC parameters, namely the transmitter keyup delay and the transmitter persistence variables.
It is therefore necessary to distinguish between command and data frames on the host/TNC link. This is done by defining the first byte of each asynchronous frame between host and TNC as a "type" indicator. The following types are defined in frames to the TNC:
Type Function Comments
0 Data frame Rest of frame is data to be sent on the HDLC channel
1 TXDELAY Second byte is transmitter keyup delay in 10 ms units
2 P Second byte of frame is persistence parameter, p:
0: p = (0+1)/256, 255: p = (255+1)/256 = 1.0
3 SLOTTIME Second byte of frame is slot interval in 10 ms units
4 TXtail Second byte of frame is time to hold up the TX after the FCS has been sent (the time allowed to send the HDLC flag character; should be at least 2 for 1200 bps operation). In 10 ms units.
The following types are defined in frames to the host:
Type Function Comments
0 Data frame Rest of frame is data from the HDLC channel
(No other types are defined; in particular, there is no provision for acknowledging data or command frames sent to the TNC.)
5.2.1.4. Persistence
The P and SLOTTIME parameters are used to implement true p-persistent CSMA. This works as follows:
Whenever the host has queued data for transmission, the TNC begins monitoring the carrier detect signal from the modem. It waits indefinitely for this signal to go inactive. Once the channel is clear, the TNC generates a random number between 0 and 255. If this number is less than or equal to P, the TNC asserts the transmitter PTT line, waits .01 * TXDELAY seconds, and transmits all frames in its queue. The TNC then releases PTT and goes back to the idle state. If the random number is greater than P, the TNC delays signal has gone active in the meantime, the TNC again waits for it to clear before continuing). Note that P=255 means always transmit as soon as possible, regardless of the random number.
The result is that the TNC waits for an exponentially-distributed random interval after sensing that the channel has gone clear before attempting to transmit. The idea here is that with proper tuning of the parameters P and SLOTTIME, several stations with traffic to send are much less likely to collide with each other when they simultaneously see the channel go clear.
5.2.2. The TNC-2 Implementation
See the files included in the TNC-2 KISS Distribution.
5.2.3. The TNC-1 Implementation
See the files included in the TNC-1 KISS Distribution.
5.2.4. The VADCG/ASHBY Implementation
See the files included in the VADCG/ASHBY KISS Distribution.
5.2.5. The AEA Implementation
All PK-232 units with WEFAX, and PC-87 units of a similar vintage, are capable of KISS operation. See the installation instructions earlier in this document for more information.
